"""Murphy (2023), Chapter 21: Variational autoencoders (and Supplement Chapter 21).

Companion code for Chapter 21 of K. P. Murphy, Probabilistic Machine Learning: Advanced Topics
(MIT Press, 2023; December 2025 draft), pp. 791-819, and the supplement, pp. 195-197. Written from
scratch with numpy, matplotlib and PyTorch (CPU only), to be read next to the lecture notes
(../ch21-variational-autoencoders.html).

Scale. Every network here is small and trained on the CPU in seconds: a subset of MNIST (20 000
training images, 2 000 test images) with one-hidden-layer multilayer perceptrons and 15 to 40 epochs
of Adam. The book trains convolutional models on CelebA for 20 minutes on a GPU; the figures below
are therefore stand-ins that show the same effects on a smaller problem, and the pictures are
blurrier and less sharp than a long GPU run would give. Every training run is seeded.

Methods
* Section 21.2: VAE with Bernoulli decoder and diagonal Gaussian encoder (class VAE, train_vae),
  Algorithm 21.1 written out for a full-covariance posterior (algorithm_21_1_loss), the
  autoencoder (the same code with deterministic codes and no KL term), the ELBO decompositions
  (21.16)-(21.22) estimated on a trained model (aggregated_posterior_terms).
* Section 21.3.1: beta-VAE (train_vae with beta), rate-distortion sweep and active units.
* Sections 21.3.2: InfoVAE objective (21.35) and the MMD penalty (21.38) (mmd2, infovae_loss).
* Section 21.3.3: product of Gaussian experts (21.47) (poe).
* Section 21.4.3 free bits (21.59), 21.5.5 residual posterior KL (21.74).
* Section 21.6: binary autoencoder with the straight-through estimator (Figure 21.15), the VQ-VAE
  codebook with the exponential-moving-average update (21.81)-(21.83) on a two-dimensional
  toy problem (vq_ema), Gumbel-softmax (21.85).
* Supplement 21.0.1: VAE with missing data, trained on masked inputs (Figure S21.2).
* An exactly solvable case that the book does not work out: the beta-weighted linear Gaussian VAE,
  which selects its latent directions by reverse water-filling (linear_vae_theory, fit_linear_vae).

Skipped figures, with reasons: Figure 21.1 (schematic of a VAE), 21.4 (diagram), 21.5, 21.6, 21.9 to 21.14,
21.16 to 21.18 and S21.1 (architecture diagrams and schematics); Figures 21.7 and 21.8 (samples from
a text VAE-RNN and from sketch-RNN: they need those models and their data, which are not
bundled); Figure 21.13 (samples from a 78-layer VDVAE trained on faces, GPU scale). Figures 21.2 and
21.3 (CelebA) are reproduced as MNIST stand-ins and Figure S21.2 likewise.

Own figures (not in the book), named as in the notes: x21.a to x21.e.

Data: MNIST (LeCun et al. 1998, the book's "off-line digits"), simulation for the toys.
"""
import os
import sys

import numpy as np

HERE = os.path.dirname(os.path.abspath(__file__))
sys.path.insert(0, HERE)
import common  # noqa: E402
from common import BLUE, CYAN, GREEN, GREY, ORANGE, PURPLE, RED, MAGENTA, plt, savefig, panel_grid, panel_label  # noqa: E402

CH = 21
CACHE_DIR = os.path.join(HERE, "cache", "ch21")
DATA_OUT = os.path.normpath(os.path.join(HERE, "..", "data"))
os.makedirs(CACHE_DIR, exist_ok=True)
torch = common.torch_setup(0)
nn = torch.nn
F = torch.nn.functional

N_TRAIN, N_TEST = 20000, 2000


# =========================================================================== data
def mnist_subset(n_train=N_TRAIN, n_test=N_TEST):
    """The first n_train training images and the first n_test test images of MNIST, as float32 in [0, 1]."""
    Xtr, ytr = common.mnist(True)
    Xte, yte = common.mnist(False)
    return (Xtr[:n_train].astype(np.float32), ytr[:n_train], Xte[:n_test].astype(np.float32), yte[:n_test])


def tensor(a):
    return torch.as_tensor(np.asarray(a), dtype=torch.float32)


# =========================================================================== the VAE (Section 21.2)
class VAE(nn.Module):
    """z ~ N(0, I_K), x | z ~ prod_d Ber(sigmoid(d_theta(z))_d), q(z|x) = N(mu(x), diag(exp(2 l(x)))).

    Encoder and decoder are one-hidden-layer MLPs. mask_inputs=True is the model of Supplement 21.0.1:
    the encoder sees (x*(1-m), m) and the likelihood is evaluated on the observed pixels only.
    """

    def __init__(self, K=16, H=400, D=784, mask_inputs=False):
        super().__init__()
        self.K, self.D, self.mask_inputs = K, D, mask_inputs
        din = 2 * D if mask_inputs else D
        self.enc = nn.Sequential(nn.Linear(din, H), nn.ReLU(), nn.Linear(H, 2 * K))
        self.dec = nn.Sequential(nn.Linear(K, H), nn.ReLU(), nn.Linear(H, D))

    def encode(self, x, m=None):
        h = torch.cat([x * (1 - m), m], 1) if self.mask_inputs else x
        mu, l = self.enc(h).chunk(2, dim=1)          # l = log sigma, as in (21.7)-(21.8)
        return mu, l

    def decode(self, z):
        return self.dec(z)                           # logits of the Bernoulli means, (21.5)


def bce_sum(logits, x, m=None):
    """Negative log likelihood of a product of Bernoullis, summed over (observed) pixels."""
    e = F.binary_cross_entropy_with_logits(logits, x, reduction="none")
    if m is not None:
        e = e * (1 - m)
    return e.sum(1)


def kl_std_normal(mu, l):
    """KL(N(mu, diag(exp(2l))) || N(0, I)) per row: 0.5 sum (mu^2 + sigma^2 - 1 - 2 l), cf. (10.50)."""
    return 0.5 * (mu ** 2 + torch.exp(2 * l) - 1 - 2 * l).sum(1)


def train_vae(X, K=16, beta=1.0, epochs=25, batch=128, lr=1e-3, seed=0, H=400, deterministic=False,
              free_bits=None, anneal_epochs=0, masks=None, verbose=False):
    """Fit a VAE (or an autoencoder when deterministic=True) to the rows of X by Adam.

    The loss per example is -E_q log p(x|z) + beta * KL(q(z|x) || N(0, I)) (21.24). beta is raised linearly
    from 0 to its final value over the first anneal_epochs epochs (KL annealing, Section 21.4.1). With
    free_bits = lam the KL of each latent coordinate is replaced by max(lam, KL_k), (21.59), computed on the
    minibatch average. A deterministic autoencoder uses z = mu(x) and has no KL term.
    masks: optional array of 0/1 'missing' indicators m (1 = missing) of the same shape as X.
    """
    torch.manual_seed(seed)
    rng = np.random.default_rng(seed)
    model = VAE(K, H, X.shape[1], mask_inputs=masks is not None)
    opt = torch.optim.Adam(model.parameters(), lr=lr)
    Xt = tensor(X)
    Mt = tensor(masks) if masks is not None else None
    n = len(Xt)
    hist = []
    for ep in range(epochs):
        b = beta if anneal_epochs == 0 else beta * min(1.0, ep / max(anneal_epochs, 1))
        perm = torch.as_tensor(rng.permutation(n))
        tot = np.zeros(3)
        for i in range(0, n - batch + 1, batch):
            idx = perm[i:i + batch]
            x = Xt[idx]
            m = Mt[idx] if Mt is not None else None
            mu, l = model.encode(x, m)
            if deterministic:
                z = mu
                kl_k = torch.zeros(1)
            else:
                z = mu + torch.exp(l) * torch.randn_like(mu)
                kl_all = 0.5 * (mu ** 2 + torch.exp(2 * l) - 1 - 2 * l)    # (batch, K)
                if free_bits is not None:
                    kl_k = torch.clamp(kl_all.mean(0), min=free_bits).sum().expand(len(x))
                else:
                    kl_k = kl_all.sum(1)
            nll = bce_sum(model.decode(z), x, m)
            loss = (nll + (0 if deterministic else b * kl_k)).mean()
            opt.zero_grad()
            loss.backward()
            opt.step()
            tot += [loss.item(), nll.mean().item(), (0.0 if deterministic else kl_all.sum(1).mean().item())]
        tot /= n // batch
        hist.append(tot)
        if verbose:
            print("epoch %d loss %.2f nll %.2f kl %.2f" % (ep, *tot))
    model.eval()
    return model, np.array(hist)


@torch.no_grad()
def evaluate(model, X, masks=None, S=1, seed=123):
    """Per-example average of the reconstruction NLL (distortion) and the KL (rate), with S samples of z."""
    g = torch.Generator().manual_seed(seed)
    x = tensor(X)
    m = tensor(masks) if masks is not None else None
    mu, l = model.encode(x, m)
    nll = 0.0
    for _ in range(S):
        z = mu + torch.exp(l) * torch.randn(mu.shape, generator=g)
        nll = nll + bce_sum(model.decode(z), x, m).mean().item() / S
    return nll, kl_std_normal(mu, l).mean().item()


@torch.no_grad()
def det_nll(model, X):
    """Reconstruction NLL of an autoencoder (z = mu(x))."""
    x = tensor(X)
    mu, _ = model.encode(x)
    return bce_sum(model.decode(mu), x).mean().item()


@torch.no_grad()
def active_units(model, X, thresh=0.01):
    """Number of latent coordinates with Var_x[mu_k(x)] above thresh (the 'active units' of Burda et al. 2016)."""
    mu, _ = model.encode(tensor(X))
    v = mu.var(0).numpy()
    return int((v > thresh).sum()), v


def cached(name, fn):
    """Run fn() once and keep its result (a dict of arrays and torch state dicts) in the private cache."""
    path = os.path.join(CACHE_DIR, name + ".pt")
    if os.path.exists(path):
        return torch.load(path, weights_only=False)
    out = fn()
    torch.save(out, path)
    return out


def cached_vae(name, X, **kw):
    """Train a VAE with train_vae(X, **kw) once and keep the weights."""
    def make():
        model, hist = train_vae(X, **kw)
        return {"state": model.state_dict(), "hist": hist, "kw": {k: v for k, v in kw.items() if k != "masks"}}
    d = cached(name, make)
    model = VAE(kw.get("K", 16), kw.get("H", 400), X.shape[1], mask_inputs=kw.get("masks") is not None)
    model.load_state_dict(d["state"])
    model.eval()
    return model, d["hist"]


# =========================================================================== Algorithm 21.1
def algorithm_21_1_loss(x, eps, mu, log_sigma, Lprime, decoder_logits_fn, printed=False):
    """The per-example loss of Algorithm 21.1 (full-covariance Gaussian posterior, Bernoulli likelihood).

    z = L eps + mu with L = M * L' + diag(sigma), M the STRICTLY LOWER triangular mask of ones. Returns
    -ELBO = -log p(x|z) - log p(z) + log q(z|x), i.e. the quantity the gradient step should decrease.
    With printed=True the loss is computed exactly as the pseudocode is printed (mask np.triu(ones, -1) and
    L = Llogpx + Llogpz - Llogqz with Llogpx the negative log likelihood); see the notes, Section 21.2.2.
    """
    K = len(mu)
    sigma = np.exp(log_sigma)
    M = np.triu(np.ones((K, K)), -1) if printed else np.tril(np.ones((K, K)), -1)
    L = M * Lprime + np.diag(sigma)
    z = L @ eps + mu
    p = 1 / (1 + np.exp(-decoder_logits_fn(z)))
    Llogqz = -np.sum(0.5 * eps ** 2 + 0.5 * np.log(2 * np.pi) + log_sigma)
    Llogpz = -np.sum(0.5 * z ** 2 + 0.5 * np.log(2 * np.pi))
    Llogpx = -np.sum(x * np.log(p) + (1 - x) * np.log(1 - p))
    if printed:
        return Llogpx + Llogpz - Llogqz
    return Llogpx - Llogpz + Llogqz


# =========================================================================== objectives of Section 21.3
def mmd2(Z1, Z2, sigma=None):
    """Biased squared maximum mean discrepancy (21.38) with the RBF kernel exp(-||z-z'||^2 / (2 sigma^2))."""
    Z1, Z2 = np.atleast_2d(Z1), np.atleast_2d(Z2)
    sigma = np.sqrt(Z1.shape[1]) if sigma is None else sigma

    def k(A, B):
        d2 = ((A[:, None, :] - B[None, :, :]) ** 2).sum(-1)
        return np.exp(-0.5 * d2 / sigma ** 2)
    return k(Z1, Z1).mean() + k(Z2, Z2).mean() - 2 * k(Z1, Z2).mean()


def poe(mus, precisions):
    """Product of Gaussian experts (21.47): the precisions add, the mean is the precision-weighted average."""
    P = sum(precisions)
    Sigma = np.linalg.inv(P)
    mu = Sigma @ sum(Pm @ m for Pm, m in zip(precisions, mus))
    return mu, Sigma


def gumbel_softmax(logq, tau, rng, n=1):
    """Relaxed one-hot samples (21.85): softmax((g + log q) / tau) with g ~ Gumbel(0, 1)."""
    g = -np.log(-np.log(rng.uniform(size=(n, len(logq)))))
    a = (g + logq) / tau
    a -= a.max(1, keepdims=True)
    e = np.exp(a)
    return e / e.sum(1, keepdims=True)


# =========================================================================== the linear Gaussian beta-VAE
def linear_vae_theory(lam, sigma2, beta):
    """Exact optimum of the beta-weighted linear Gaussian VAE along each principal direction.

    Data covariance eigenvalues lam, decoder noise variance sigma2, KL weight beta. Direction i is active iff
    lam_i > beta*sigma2; then u_i = lam_i/(beta*sigma2) = 1 + SNR, the rate is (1/2) log u_i, the remaining mean
    squared reconstruction error is beta*sigma2 (reverse water-filling) and the posterior variance is 1/u_i.
    Returns rate_i, dist_i (mean squared error in direction i), loss_i (distortion/(2 sigma2) + beta*rate).
    """
    lam = np.asarray(lam, float)
    u = np.maximum(lam / (beta * sigma2), 1.0)
    rate = 0.5 * np.log(u)
    dist = lam / u
    loss = dist / (2 * sigma2) + beta * rate
    return rate, dist, loss, u


def fit_linear_vae(Sigma, sigma2, beta, K=None, steps=3000, seed=0, free_bits=None, return_units=False):
    """Minimise the exact expected beta-ELBO of a linear VAE by Adam (no sampling noise).

    z | x ~ N(A x, diag(s^2)), x | z ~ N(W z, sigma2 I). For zero-mean data with covariance Sigma:
    E||x - W z||^2 = tr Sigma - 2 tr(W A Sigma) + tr(W (A Sigma A^T + diag s^2) W^T),
    E KL = (1/2) sum_k [ (A Sigma A^T)_kk + s_k^2 - 1 - log s_k^2 ]. Returns the loss (with the free-bits hinge if free_bits is given), the mean squared error, the rate (and, with
    return_units, the KL of each latent unit).
    """
    torch.manual_seed(seed)
    D = Sigma.shape[0]
    K = K or D
    S = torch.as_tensor(Sigma, dtype=torch.float64)
    A = (0.3 * torch.randn(K, D, dtype=torch.float64)).requires_grad_()
    W = (0.3 * torch.randn(D, K, dtype=torch.float64)).requires_grad_()
    ls = torch.zeros(K, dtype=torch.float64, requires_grad=True)     # log s_k
    opt = torch.optim.Adam([A, W, ls], lr=0.02)

    def terms():
        ASA = A @ S @ A.T
        s2 = torch.exp(2 * ls)
        mse = torch.trace(S) - 2 * torch.trace(W @ A @ S) + torch.trace(W @ (ASA + torch.diag(s2)) @ W.T)
        kl_k = 0.5 * (torch.diagonal(ASA) + s2 - 1 - 2 * ls)
        rate = kl_k.sum()
        if free_bits is not None:                       # hinge of (21.59): units below lam are free
            return mse, rate, torch.clamp(kl_k, min=free_bits).sum(), kl_k
        return mse, rate, rate, kl_k
    for it in range(steps):
        opt.zero_grad()
        mse, rate, pen, _ = terms()
        (mse / (2 * sigma2) + beta * pen).backward()
        opt.step()
        if it == int(0.7 * steps):
            for g in opt.param_groups:
                g["lr"] = 0.003
    mse, rate, pen, kl_k = terms()
    out = ((mse / (2 * sigma2) + beta * pen).item(), mse.item(), rate.item())
    return out + (kl_k.detach().numpy(),) if return_units else out


# =========================================================================== VQ codebook with EMA (21.81)-(21.83)
def vq_ema(Z, K, gamma=0.9, steps=60, batch=64, init=None, seed=0, laplace=False):
    """Online codebook learning with the exponential moving averages of the VQ-VAE (21.81)-(21.83).

    Z: encoder outputs (n, d) (here the data themselves: the encoder is the identity). Each step assigns a
    minibatch to the nearest codes, updates N_i <- gamma N_i + (1-gamma) n_i, m_i <- gamma m_i + (1-gamma) sum_j z_ij
    and sets e_i = m_i / N_i. Codes are initialised at `init` with N_i = 1, m_i = e_i. Returns the codebook after each
    step (steps+1, K, d), the distortion of the whole data set after each step and the final counts N.
    """
    rng = np.random.default_rng(seed)
    e = np.array(init, float) if init is not None else Z[rng.choice(len(Z), K, replace=False)].copy()
    N = np.ones(K)
    m = e.copy()
    hist = [e.copy()]
    dist = []

    def distortion(e_):
        d2 = ((Z[:, None, :] - e_[None]) ** 2).sum(-1)
        return d2.min(1).mean()
    dist.append(distortion(e))
    for t in range(steps):
        zb = Z[rng.choice(len(Z), batch, replace=False)]
        a = ((zb[:, None, :] - e[None]) ** 2).sum(-1).argmin(1)
        nt = np.bincount(a, minlength=K).astype(float)
        st = np.zeros_like(e)
        np.add.at(st, a, zb)
        N = gamma * N + (1 - gamma) * nt
        m = gamma * m + (1 - gamma) * st
        e = m / np.maximum(N, 1e-12)[:, None]
        hist.append(e.copy())
        dist.append(distortion(e))
    return np.array(hist), np.array(dist), N


def toy_blobs(n=2000, seed=0):
    """Two-dimensional data for the VQ toy: five Gaussian blobs of different sizes (reused by the demo)."""
    rng = np.random.default_rng(seed)
    centres = np.array([[-2.0, -1.5], [-1.0, 1.8], [0.6, -0.4], [2.2, 1.4], [2.4, -1.8]])
    sd = np.array([0.35, 0.3, 0.4, 0.3, 0.25])
    w = np.array([0.25, 0.2, 0.25, 0.15, 0.15])
    c = rng.choice(5, n, p=w)
    return centres[c] + sd[c, None] * rng.standard_normal((n, 2)), c, centres


# =========================================================================== aggregated posterior and the rate decomposition
@torch.no_grad()
def aggregated_posterior_terms(model, X, n_z=1, seed=7):
    """Estimate, for a model with a low-dimensional latent code, the pieces of (21.22) and the rate.

    The aggregated posterior q(z) = (1/N) sum_n N(z | mu_n, diag sigma_n^2) is a mixture of N Gaussians, so
    log q(z) is exact. With one z drawn from each q(z|x_n):
      rate R = E KL(q(z|x)||p(z)) (closed form), I_q(x; z) = E[log q(z|x) - log q(z)] (mutual information
      under the empirical data distribution), KL(q(z)||p(z)) = E[log q(z) - log p(z)], and R = I + KL_agg.
    """
    x = tensor(X)
    mu, l = model.encode(x)
    g = torch.Generator().manual_seed(seed)
    N, K = mu.shape
    z = mu + torch.exp(l) * torch.randn(mu.shape, generator=g)
    s2 = torch.exp(2 * l)
    # log N(z_n | mu_j, s2_j) for all pairs (n, j): shape (N, N)
    d = z[:, None, :] - mu[None, :, :]
    lp = -0.5 * (d ** 2 / s2[None] + torch.log(2 * np.pi * s2[None])).sum(-1)
    logq = torch.logsumexp(lp, 1) - np.log(N)
    logq_cond = torch.diagonal(lp)
    logp = -0.5 * (z ** 2 + np.log(2 * np.pi)).sum(1)
    rate = kl_std_normal(mu, l).mean().item()
    I = (logq_cond - logq).mean().item()
    klagg = (logq - logp).mean().item()
    return rate, I, klagg


# =========================================================================== image grids
def image_grid(imgs, nrow, ncol, pad=1, side=28):
    """Tile images (n, side*side) into one array."""
    G = np.ones((nrow * (side + pad) + pad, ncol * (side + pad) + pad))
    for k, im in enumerate(imgs[:nrow * ncol]):
        r, c = divmod(k, ncol)
        G[pad + r * (side + pad):pad + r * (side + pad) + side, pad + c * (side + pad):pad + c * (side + pad) + side] = 1 - im.reshape(side, side)
    return G


@torch.no_grad()
def decode_probs(model, Z):
    return torch.sigmoid(model.decode(tensor(Z))).numpy()


# =========================================================================== binary autoencoder (Section 21.6.1)
class BinaryAE(nn.Module):
    """x -> 256 binary code (hard threshold, straight-through gradient) -> reconstruction, loss (21.75)."""

    def __init__(self, nbits=256, H=512, D=784):
        super().__init__()
        self.enc = nn.Sequential(nn.Linear(D, H), nn.ReLU(), nn.Linear(H, nbits))
        self.dec = nn.Sequential(nn.Linear(nbits, H), nn.ReLU(), nn.Linear(H, D), nn.Sigmoid())

    def code(self, x, straight_through=True):
        s = torch.sigmoid(self.enc(x))
        hard = (s > 0.5).float()
        return s + (hard - s).detach() if straight_through else hard

    def forward(self, x):
        return self.dec(self.code(x))


def train_binary_ae(X, nbits=256, epochs=30, batch=128, lr=1e-3, seed=0):
    torch.manual_seed(seed)
    rng = np.random.default_rng(seed)
    model = BinaryAE(nbits, 512, X.shape[1])
    opt = torch.optim.Adam(model.parameters(), lr=lr)
    Xt = tensor(X)
    hist = []
    for ep in range(epochs):
        perm = torch.as_tensor(rng.permutation(len(Xt)))
        tot = 0.0
        for i in range(0, len(Xt) - batch + 1, batch):
            x = Xt[perm[i:i + batch]]
            loss = ((x - model(x)) ** 2).sum(1).mean()      # ||x - d(e(x))||^2, (21.75)
            opt.zero_grad()
            loss.backward()
            opt.step()
            tot += loss.item()
        hist.append(tot / (len(Xt) // batch))
    model.eval()
    return model, np.array(hist)


# =========================================================================== missing data (Supplement 21.0.1)
def make_masks(n, seed=0, side=28):
    """Missingness masks m (1 = missing): half of the images lose a random fraction (20% to 80%) of their pixels
    completely at random, half lose one square block of side 8 to 16 at a random place."""
    rng = np.random.default_rng(seed)
    M = np.zeros((n, side * side), np.float32)
    for i in range(n):
        if rng.random() < 0.5:
            M[i] = rng.random(side * side) < rng.uniform(0.2, 0.8)
        else:
            b = rng.integers(8, 17)
            r, c = rng.integers(0, side - b + 1, 2)
            G = np.zeros((side, side), np.float32)
            G[r:r + b, c:c + b] = 1
            M[i] = G.ravel()
    return M


@torch.no_grad()
def impute(model, X, M):
    """Fill the missing pixels with the decoder mean at z = mu(x_o, m); observed pixels are kept."""
    x, m = tensor(X), tensor(M)
    mu, _ = model.encode(x, m)
    p = torch.sigmoid(model.decode(mu))
    return (x * (1 - m) + p * m).numpy(), p.numpy()


# =========================================================================== trained models shared by the figures
BETAS_SWEEP = (0.1, 0.25, 0.5, 1.0, 2.0, 4.0, 8.0, 16.0)
BETAS_2D = (0.0, 0.25, 0.5, 1.0, 2.0, 4.0)          # beta = 0 is the deterministic autoencoder


def models_21_2():
    """The three models of Figures 21.2 and 21.3: autoencoder, beta-VAE with beta = 0.5, VAE; 16 latent dimensions."""
    Xtr, ytr, Xte, yte = mnist_subset()
    ae, _ = cached_vae("ae16", Xtr, K=16, epochs=25, deterministic=True, beta=0.0)
    b05, _ = cached_vae("bvae16_0.5", Xtr, K=16, epochs=25, beta=0.5)
    vae, _ = cached_vae("vae16_1", Xtr, K=16, epochs=25, beta=1.0)
    return (ae, b05, vae), Xte


def models_2d():
    """Two-dimensional-latent models for beta in BETAS_2D (0 = deterministic autoencoder)."""
    Xtr, ytr, Xte, yte = mnist_subset()
    out = {}
    for b in BETAS_2D:
        kw = dict(K=2, epochs=30, H=256, beta=b, deterministic=(b == 0))
        out[b], _ = cached_vae("vae2d_%g" % b, Xtr, **kw)
    return out, Xte, yte


def show_rows(fig, ax, G, labels=None, **kw):
    ax.imshow(G, cmap="gray", vmin=0, vmax=1, interpolation="nearest", **kw)
    ax.set_xticks([])
    ax.set_yticks([])
    for s in ax.spines.values():
        s.set_visible(False)


def rows_image(rows, ncol, side=28, pad=2):
    """rows: list of (ncol, side*side) arrays -> one image with a blank line between rows."""
    H = len(rows) * (side + pad) + pad
    W = ncol * (side + pad) + pad
    G = np.ones((H, W))
    for r, imgs in enumerate(rows):
        for c in range(ncol):
            G[pad + r * (side + pad):pad + r * (side + pad) + side, pad + c * (side + pad):pad + c * (side + pad) + side] = 1 - imgs[c].reshape(side, side)
    return G


# =========================================================================== Figures 21.2 and 21.3
def fig_21_2(out=None):
    """Prior samples z ~ N(0, I) decoded by an autoencoder, a beta-VAE (beta = 0.5) and a VAE (MNIST stand-in for CelebA)."""
    (ae, b05, vae), Xte = models_21_2()
    rng = np.random.default_rng(3)
    Z = rng.standard_normal((12, 16)).astype(np.float32)
    rows = [decode_probs(m, Z) for m in (ae, b05, vae)]
    G = rows_image(rows, 12)
    fig, ax = plt.subplots(figsize=(6.4, 1.8))
    show_rows(fig, ax, G)
    for r, lab in enumerate(["autoencoder", r"$\beta$-VAE, $\beta=0.5$", "VAE"]):
        ax.text(-4, 2 + r * 30 + 14, lab, ha="right", va="center", fontsize=8)
    fig.tight_layout()
    savefig(fig, CH, "fig21-2", out)


def fig_21_3(out=None):
    """Reconstructions of test images by the three models of Figure 21.2."""
    (ae, b05, vae), Xte = models_21_2()
    x = Xte[:12]
    rows = [x]
    with torch.no_grad():
        for m in (ae, b05, vae):
            mu, _ = m.encode(tensor(x))
            rows.append(torch.sigmoid(m.decode(mu)).numpy())
    G = rows_image(rows, 12)
    fig, ax = plt.subplots(figsize=(6.4, 2.3))
    show_rows(fig, ax, G)
    for r, lab in enumerate(["original", "autoencoder", r"$\beta$-VAE, $\beta=0.5$", "VAE"]):
        ax.text(-4, 2 + r * 30 + 14, lab, ha="right", va="center", fontsize=8)
    fig.tight_layout()
    savefig(fig, CH, "fig21-3", out)


# =========================================================================== Figure 21.15
def fig_21_15(out=None):
    """Autoencoder with 256 binary latents, straight-through training; inputs, reconstructions and the codes as 16x16 images."""
    Xtr, ytr, Xte, yte = mnist_subset()

    def make():
        b, h = train_binary_ae(Xtr, epochs=30)
        return {"state": b.state_dict(), "hist": h}
    d = cached("binary_ae256", make)
    b = BinaryAE(256, 512, 784)
    b.load_state_dict(d["state"])
    b.eval()
    x = tensor(Xte[:12])
    with torch.no_grad():
        code = b.code(x, False)
        rec = b.dec(code).numpy()
    rows = [Xte[:12], rec, code.numpy()]
    H = 3 * 30 + 2
    G = rows_image(rows[:2], 12)
    fig, axes = plt.subplots(2, 1, figsize=(6.4, 2.6), gridspec_kw={"height_ratios": [2, 1.0]})
    show_rows(fig, axes[0], G)
    for r, lab in enumerate(["input", "reconstruction"]):
        axes[0].text(-4, 2 + r * 30 + 14, lab, ha="right", va="center", fontsize=8)
    C = np.ones((18, 12 * 18 + 2))
    for c in range(12):
        C[1:17, 2 + c * 18:2 + c * 18 + 16] = 1 - code.numpy()[c].reshape(16, 16)
    show_rows(fig, axes[1], C)
    axes[1].text(-4, 9, "256-bit code", ha="right", va="center", fontsize=8)
    fig.tight_layout()
    savefig(fig, CH, "fig21-15", out)
    with torch.no_grad():
        xt = tensor(Xte)
        return ((xt - b(xt)) ** 2).sum(1).mean().item(), float(b.code(xt, False).mean())


# =========================================================================== Figure S21.2
def models_missing():
    Xtr, ytr, Xte, yte = mnist_subset()
    Mtr = make_masks(len(Xtr), 1)
    m, _ = cached_vae("vae16_missing", Xtr, K=16, epochs=30, beta=1.0, masks=Mtr)
    return m, Xte


def fig_S21_2(out=None):
    """Imputing missing pixels with a VAE trained on masked images (MNIST stand-in for the book's face images)."""
    m, Xte = models_missing()
    n = 8
    rng = np.random.default_rng(5)
    x = Xte[100:100 + n]
    M = np.zeros((n, 784), np.float32)
    # first four: random 50% pixel loss; last four: one block
    for i in range(4):
        M[i] = rng.random(784) < 0.5
    for i in range(4, 8):
        b = 12
        r, c = rng.integers(2, 14, 2)
        G = np.zeros((28, 28), np.float32)
        G[r:r + b, c:c + b] = 1
        M[i] = G.ravel()
    filled, p = impute(m, x, M)
    rows = [x]
    mask_rgb = np.ones((n, 28, 28, 3))
    corr_rgb = np.ones((n, 28, 28, 3))
    for i in range(n):
        g = (1 - x[i]).reshape(28, 28)
        mm = M[i].reshape(28, 28).astype(bool)
        mask_rgb[i] = np.stack([g, g, g], -1)
        mask_rgb[i][mm] = [1.0, 0.65, 0.25]
        corr_rgb[i] = np.stack([g, g, g], -1)
        corr_rgb[i][mm] = [0.55, 0.55, 0.55]
    fig, axes = plt.subplots(4, 1, figsize=(6.0, 3.4))
    pad, side = 2, 28

    def strip(imgs_rgb):
        G = np.ones((side + 2 * pad, n * (side + pad) + pad, 3))
        for c in range(n):
            G[pad:pad + side, pad + c * (side + pad):pad + c * (side + pad) + side] = imgs_rgb[c]
        return G
    gray = lambda a: np.stack([1 - a.reshape(-1, 28, 28)] * 3, -1)
    for ax, imgs, lab in zip(axes, [gray(x), mask_rgb, corr_rgb, gray(filled)], ["original $x$", "mask $m$ (orange = missing)", r"corrupted $\tilde{x}$", "VAE imputation"]):
        ax.imshow(strip(imgs), interpolation="nearest")
        ax.set_xticks([])
        ax.set_yticks([])
        for s in ax.spines.values():
            s.set_visible(False)
        ax.text(-4, 16, lab, ha="right", va="center", fontsize=8)
    fig.tight_layout(h_pad=0.2)
    savefig(fig, CH, "figS21-2", out)
    return filled, M


# =========================================================================== own figures
def decoded_grid(model, xlim, ylim, n=10):
    xs = np.linspace(*xlim, n)
    ys = np.linspace(*ylim, n)[::-1]
    Z = np.array([[x, y] for y in ys for x in xs], np.float32)
    return image_grid(decode_probs(model, Z), n, n), Z


def fig_x21_a(out=None):
    """Own figure: 2-d latent codes and decoded latent grids of an autoencoder and VAEs with beta = 1 and beta = 4."""
    models, Xte, yte = models_2d()
    sel = (0.0, 1.0, 4.0)
    fig, axes = panel_grid(2, 3, size=(2.7, 2.7))
    cmap = plt.get_cmap("tab10")
    for j, b in enumerate(sel):
        m = models[b]
        with torch.no_grad():
            mu, _ = m.encode(tensor(Xte))
        mu = mu.numpy()
        ax = axes[0, j]
        ax.scatter(mu[:, 0], mu[:, 1], c=yte, cmap="tab10", s=3, alpha=0.7, linewidths=0)
        if b > 0:
            t = np.linspace(0, 2 * np.pi, 200)
            ax.plot(2 * np.cos(t), 2 * np.sin(t), color="k", lw=0.8, ls="--")
            lim = 3.2
            ax.set_xlim(-lim, lim)
            ax.set_ylim(-lim, lim)
            xl, yl = (-2.5, 2.5), (-2.5, 2.5)
        else:
            xl = tuple(np.quantile(mu[:, 0], [0.02, 0.98]))
            yl = tuple(np.quantile(mu[:, 1], [0.02, 0.98]))
        ax.set_title("autoencoder" if b == 0 else r"$\beta=%g$" % b, fontsize=9)
        ax.set_xlabel("$z_1$")
        ax.set_ylabel("$z_2$")
        G, _ = decoded_grid(m, xl, yl)
        ax = axes[1, j]
        ax.imshow(G, cmap="gray", vmin=0, vmax=1, interpolation="nearest")
        ax.set_xticks([])
        ax.set_yticks([])
        ax.set_title("decoded grid on [%.1f, %.1f] x [%.1f, %.1f]" % (xl[0], xl[1], yl[0], yl[1]), fontsize=7)
    handles = [plt.Line2D([], [], marker="o", ls="", color=cmap(k), ms=3, label=str(k)) for k in range(10)]
    axes[0, 2].legend(handles=handles, ncol=2, fontsize=6, frameon=False, loc="lower right", handletextpad=0.1, columnspacing=0.5)
    fig.tight_layout()
    savefig(fig, CH, "figx21-a", out)


def beta_sweep():
    """Test-set rate and distortion, and the number of active latent units, of K = 16 beta-VAEs (cached)."""
    Xtr, ytr, Xte, yte = mnist_subset()

    def make():
        res = []
        for b in BETAS_SWEEP:
            m, _ = train_vae(Xtr, K=16, epochs=20, beta=b)
            nll, kl = evaluate(m, Xte, S=4)
            au, _ = active_units(m, Xte)
            res.append((b, nll, kl, au))
        m, _ = train_vae(Xtr, K=16, epochs=20, beta=0.0, deterministic=True)
        return {"res": np.array(res), "ae": det_nll(m, Xte)}
    return cached("beta_sweep", make)


def fig_x21_b(out=None):
    """Own figure: the rate-distortion curve traced by beta, and the number of active units against beta."""
    d = beta_sweep()
    r = d["res"]
    fig, axes = panel_grid(1, 2, size=(3.5, 3.0))
    ax = axes[0, 0]
    ax.plot(r[:, 2], r[:, 1], "-o", color=BLUE, ms=4)
    for b, nll, kl, au in r:
        ax.annotate(r"$\beta$=%g" % b, (kl, nll), textcoords="offset points", xytext=(4, 4), fontsize=7)
    ax.axhline(d["ae"], color=RED, ls="--", lw=1)
    ax.text(2, d["ae"] - 7, "autoencoder (no KL term)", color=RED, fontsize=7, ha="left")
    ax.set_xlabel("rate: $\\mathbb{E}\\,\\mathrm{KL}(q(z|x)\\|p(z))$ (nats)")
    ax.set_ylabel("distortion: $-\\mathbb{E}\\log p(x|z)$ (nats)")
    panel_label(ax, "a", "upper right")
    ax = axes[0, 1]
    ax.semilogx(r[:, 0], r[:, 3], "-o", color=GREEN, ms=4)
    ax.set_xlabel(r"$\beta$")
    ax.set_ylabel("active latent units (of 16)")
    ax.set_ylim(0, 17)
    panel_label(ax, "b", "lower left")
    fig.tight_layout()
    savefig(fig, CH, "figx21-b", out)
    return d


def fig_x21_c(out=None):
    """Own figure: the rate of 2-d VAEs split into mutual information and the aggregated-posterior KL, (21.22)."""
    models, Xte, yte = models_2d()
    bs = [b for b in BETAS_2D if b > 0]
    res = np.array([aggregated_posterior_terms(models[b], Xte) for b in bs])
    fig, axes = panel_grid(1, 1, size=(4.2, 3.0))
    ax = axes[0, 0]
    x = np.arange(len(bs))
    ax.bar(x, res[:, 1], color=BLUE, label=r"mutual information $I_q(x;z)$")
    ax.bar(x, res[:, 2], bottom=res[:, 1], color=ORANGE, label=r"$\mathrm{KL}(q(z)\,\|\,p(z))$")
    ax.plot(x, res[:, 0], "k_", ms=14, mew=1.5, label="rate (their sum)")
    ax.set_xticks(x)
    ax.set_xticklabels(["%g" % b for b in bs])
    ax.set_xlabel(r"$\beta$")
    ax.set_ylabel("nats")
    ax.legend(frameon=False, fontsize=7)
    fig.tight_layout()
    savefig(fig, CH, "figx21-c", out)
    return bs, res


# the spectrum used for the linear VAE and its demo: eigenvalues of the MNIST pixel covariance
def mnist_spectrum(k=60):
    Xtr, ytr, Xte, yte = mnist_subset()
    ev = np.linalg.eigvalsh(np.cov(Xtr.T.astype(np.float64)))[::-1]
    return ev[:k]


LIN_LAM = np.array([4.0, 2.0, 1.0, 0.5, 0.25, 0.1])
LIN_SIGMA2 = 0.25


def fig_x21_d(out=None):
    """Own figure: reverse water-filling of the linear beta-VAE: active directions, and theory against training."""
    lam_all = mnist_spectrum(784)
    lam = lam_all[:100]
    fig, axes = panel_grid(1, 3, size=(3.0, 2.8))
    ax = axes[0, 0]
    ax.semilogy(np.arange(1, 101), lam, color=GREY, lw=1.4)
    for b, c in [(1, BLUE), (4, GREEN), (16, RED)]:
        ax.axhline(b * 0.05, color=c, ls="--", lw=1)
        ax.text(98, b * 0.05 * 1.15, r"$\beta\sigma^2$, $\beta=%d$" % b, color=c, fontsize=7, ha="right")
    ax.set_xlabel("component $i$")
    ax.set_ylabel(r"eigenvalue $\lambda_i$")
    panel_label(ax, "a", "upper right")
    ax = axes[0, 1]
    bs = np.logspace(-1, 2, 60)
    for s2, c in [(0.02, BLUE), (0.05, GREEN), (0.2, RED)]:
        ax.semilogx(bs, [(lam_all > b * s2).sum() for b in bs], color=c, label=r"$\sigma^2=%g$" % s2)
    ax.set_xlabel(r"$\beta$")
    ax.set_ylabel(r"active directions")
    ax.legend(frameon=False, fontsize=7)
    panel_label(ax, "b", "upper right")
    ax = axes[0, 2]
    Sig = np.diag(LIN_LAM)
    bgrid = np.logspace(-1.3, 1.3, 40)
    th = [linear_vae_theory(LIN_LAM, LIN_SIGMA2, b) for b in bgrid]
    ax.semilogx(bgrid, [t[0].sum() for t in th], color=BLUE, label="rate, theory")
    ax.semilogx(bgrid, [t[1].sum() for t in th], color=RED, label="squared error, theory")
    fit = [fit_linear_vae(Sig, LIN_SIGMA2, b, steps=2500, seed=1) for b in np.logspace(-1.3, 1.3, 8)]
    ax.semilogx(np.logspace(-1.3, 1.3, 8), [f[2] for f in fit], "o", color=BLUE, ms=4, mfc="none", label="rate, trained")
    ax.semilogx(np.logspace(-1.3, 1.3, 8), [f[1] for f in fit], "s", color=RED, ms=4, mfc="none", label="squared error, trained")
    ax.set_xlabel(r"$\beta$")
    ax.set_ylabel("nats  /  squared error")
    ax.legend(frameon=False, fontsize=6.5)
    panel_label(ax, "c", "lower left")
    fig.tight_layout()
    savefig(fig, CH, "figx21-d", out)


def fig_x21_e(out=None):
    """Own figure: the exponential-moving-average codebook update of the VQ-VAE on blobs, for three decay rates."""
    Z, c, centres = toy_blobs()
    init = np.array([[-0.4, 0.3], [0.2, 0.5], [0.0, -0.2], [-0.3, -0.5], [0.4, 0.0], [0.5, -0.4], [4.5, 4.0], [-4.5, 3.5]])
    fig, axes = panel_grid(1, 4, size=(2.5, 2.6))
    cols = [BLUE, GREEN, RED]
    D = {}
    for j, g in enumerate((0.5, 0.9, 0.99)):
        hist, dist, N = vq_ema(Z, 8, gamma=g, steps=120, batch=64, init=init, seed=2)
        D[g] = dist
        ax = axes[0, j]
        ax.scatter(Z[:, 0], Z[:, 1], s=2, color="0.8", linewidths=0)
        for k in range(8):
            ax.plot(hist[:, k, 0], hist[:, k, 1], color=cols[j], lw=0.8, alpha=0.8)
        ax.plot(hist[-1, :, 0], hist[-1, :, 1], "k*", ms=7)
        ax.set_title(r"$\gamma=%g$" % g, fontsize=9)
        ax.set_xlim(-4.8, 4.8)
        ax.set_ylim(-3.2, 4.4)
        panel_label(ax, "abc"[j], "lower left")
    ax = axes[0, 3]
    for g, cc in zip(D, cols):
        ax.semilogy(D[g], color=cc, label=r"$\gamma=%g$" % g)
    ax.set_xlabel("step")
    ax.set_ylabel("quantisation error")
    ax.legend(frameon=False, fontsize=7)
    panel_label(ax, "d", "upper right")
    fig.tight_layout()
    savefig(fig, CH, "figx21-e", out)
    return D


# =========================================================================== JSON for the demonstrations
DEMO_BETAS = (0.0, 0.25, 1.0, 4.0)
GRID_N = 21
B36 = "0123456789abcdefghijklmnopqrstuvwxyz"


def hole_fraction(codes, n=4000, radius=0.4, seed=5):
    """Fraction of prior draws z ~ N(0, I) whose nearest stored code (posterior mean) is farther than radius."""
    z = np.random.default_rng(seed).standard_normal((n, codes.shape[1]))
    d = np.sqrt(((z[:, None, :] - codes[None]) ** 2).sum(-1)).min(1)
    return float((d > radius).mean())


def encode_numpy(model, X):
    with torch.no_grad():
        mu, l = model.encode(tensor(X))
    return mu.numpy(), np.exp(l.numpy())


def export_json():
    os.makedirs(DATA_OUT, exist_ok=True)
    import json
    models, Xte, yte = models_2d()
    n_codes = 1000
    for b in DEMO_BETAS:
        m = models[b]
        mu, sd = encode_numpy(m, Xte)
        if b > 0:
            xl, yl = (-3.0, 3.0), (-3.0, 3.0)
        else:
            xl = tuple(float(v) for v in np.quantile(mu[:, 0], [0.02, 0.98]))
            yl = tuple(float(v) for v in np.quantile(mu[:, 1], [0.02, 0.98]))
        xs, ys = np.linspace(*xl, GRID_N), np.linspace(*yl, GRID_N)
        Z = np.array([[x, y] for y in ys for x in xs], np.float32)        # row-major: y outer, x inner
        P = decode_probs(m, Z)
        cells = ["".join(B36[int(round(35 * v))] for v in row) for row in P]
        if b > 0:
            nll, kl = evaluate(m, Xte, S=4)
            rate, I, klagg = aggregated_posterior_terms(m, Xte)
        else:
            nll, kl, rate, I, klagg = det_nll(m, Xte), None, None, None, None
        out = {
            "beta": b, "xlim": xl, "ylim": yl, "n": GRID_N, "cells": cells,
            "codes": [[round(float(a), 3), round(float(c), 3), int(k)] for (a, c), k in zip(mu[:n_codes], yte[:n_codes])],
            "sd": [[round(float(a), 3), round(float(c), 3)] for a, c in sd[:n_codes]],
            "nll": nll, "rate": None if kl is None else float(kl), "mi": None if I is None else float(I),
            "klagg": None if klagg is None else float(klagg),
            "hole": hole_fraction(mu[:n_codes]),
            "code_sd": [float(v) for v in mu.std(0)],
        }
        with open(os.path.join(DATA_OUT, "ch21-latent-%s.json" % ("ae" if b == 0 else ("%g" % b).replace(".", "p"))), "w") as f:
            json.dump(out, f, separators=(",", ":"))
    # VQ toy
    Z, c, centres = toy_blobs(800, seed=1)
    Z = np.round(Z, 3)                                                # the browser sees the rounded data
    init = np.array([[-0.4, 0.3], [0.2, 0.5], [0.0, -0.2], [-0.3, -0.5], [0.4, 0.0], [0.5, -0.4], [4.5, 4.0], [-4.5, 3.5]])
    ref = {}
    for g in (0.5, 0.9, 0.99):
        hist, dist, N = vq_ema(Z, 8, gamma=g, steps=60, batch=len(Z), init=init, seed=0)
        ref["g%g" % g] = {"final_dist": float(dist[-1]), "codes": hist[-1].round(4).tolist(), "N": N.round(5).tolist()}
    e = init.copy()
    for _ in range(100):                                              # Lloyd k-means from the same start
        a = ((Z[:, None, :] - e[None]) ** 2).sum(-1).argmin(1)
        for k in range(8):
            if (a == k).any():
                e[k] = Z[a == k].mean(0)
    kmeans = float((((Z[:, None, :] - e[None]) ** 2).sum(-1)).min(1).mean())
    with open(os.path.join(DATA_OUT, "ch21-vq.json"), "w") as f:
        json.dump({"data": Z.round(3).tolist(), "init": init.tolist(), "ref": ref, "kmeans": kmeans}, f, separators=(",", ":"))
    # linear VAE spectrum
    lam = mnist_spectrum(784)
    with open(os.path.join(DATA_OUT, "ch21-linear.json"), "w") as f:
        json.dump({"mnist": [float("%.5g" % v) for v in lam], "mnist_total": float(lam.sum())}, f, separators=(",", ":"))


FIGURES = {
    "21.2": fig_21_2, "21.3": fig_21_3, "21.15": fig_21_15, "S21.2": fig_S21_2,
    "x21.a": fig_x21_a, "x21.b": fig_x21_b, "x21.c": fig_x21_c, "x21.d": fig_x21_d, "x21.e": fig_x21_e,
}


if __name__ == "__main__":
    if "--json" in sys.argv:
        export_json()
    else:
        common.run(FIGURES, CH)
        if "--fig" not in sys.argv and "--list" not in sys.argv:
            export_json()
