"""4장 · 딥러닝 기초와 분류 손실: 뒤 장들이 당연하게 쓰는 부품을 숫자로 확인한다.

무엇을 하나
  1. 활성 함수 ReLU · GELU · SiLU 를 식 그대로 구현해 PyTorch 내장과 대조한다        → figures/ch04-activations.png
  2. 2층 스칼라 신경망의 역전파를 손계산 식 그대로 계산하고 autograd 와 대조한다
  3. Adam · Adam+L2 · AdamW 한 스텝을 직접 구현해 torch.optim 과 대조한다
  4. 시그모이드 · BCE(수치 안정 형태) · 부드러운 목표 · 소프트맥스 CE 를 구현 · 대조한다
  5. 포컬 손실을 공식 구현(rfdetr criterion.py 의 sigmoid_focal_loss)과 같은 형태로 구현하고,
     기울기 식 · 사전 확률 편향 초기화의 초기 손실을 계산한다                        → figures/ch04-losses.png
  6. 배치 정규화 · 층 정규화 손계산, 배치 크기에 따른 통계의 흔들림                   → figures/ch04-norm.png
  7. 잔차 연결이 있을 때와 없을 때 첫 층까지 닿는 기울기 크기
  8. 합성곱 출력 크기, 스트라이드 = 커널인 합성곱이 "패치 나누기 + 선형 층" 과 같음을 확인
  9. 불균형 실험: 도형 중심이 있는 격자 칸 찾기(양성 약 0.6%)를
     (a) BCE + 기본 편향 (b) BCE + 사전 확률 편향 (c) 포컬 + 사전 확률 편향 으로 학습해 비교
                                                     → figures/ch04-centers.png, figures/ch04-imbalance.png
 10. 도형 하나짜리 그림을 분류하는 작은 CNN 을 학습 고리 5단계로 학습               → figures/ch04-shape-cnn.png

실행
  python ch04_basics.py            # 본문 결과 (8GB 노트북 GPU 를 다른 작업과 함께 쓰는 상태에서 5분 40초.
                                   #  대부분 9번 실험: 3설정 × 시드 3개 × AdamW 30 에폭 + SGD 12 에폭)
  python ch04_basics.py --quick    # 축소판 (같은 조건에서 약 20초)
그림은 --fig-dir (기본 figures/) 에 저장된다. 같은 폴더에 rf_shapes.py 가 있어야 한다.
7 · 9 · 11장의 실습 파일이 이 파일의 bce_with_logits · sigmoid_focal_loss · prior_bias 와 같은 식을 다시 쓴다.
"""

from __future__ import annotations

import argparse
import math
import os
import time

import matplotlib

matplotlib.use("Agg")
import matplotlib.pyplot as plt
import numpy as np
import torch
import torch.nn as nn
import torch.nn.functional as F

from rf_shapes import CLASS_NAMES, NUM_CLASSES, ShapesDataset

# 색맹에도 구별되는 색 (Okabe – Ito) 과 선 모양
COLORS = ["#0072B2", "#D55E00", "#009E73", "#CC79A7", "#E69F00", "#56B4E9"]
STYLES = ["-", "--", "-.", ":", (0, (5, 1)), (0, (3, 1, 1, 1))]


def pick_device() -> str:
    if torch.cuda.is_available():
        return "cuda"
    if torch.backends.mps.is_available():
        return "mps"
    return "cpu"


def save_figure(fig, fig_dir: str, name: str) -> None:
    os.makedirs(fig_dir, exist_ok=True)
    path = os.path.join(fig_dir, name)
    fig.savefig(path, dpi=120)
    plt.close(fig)
    print(f"  그림 저장: {name}")


# ─────────────────────────────────────────────────────────────
# 1. 활성 함수
# ─────────────────────────────────────────────────────────────

# --8<-- [start:activations]
def relu(x: torch.Tensor) -> torch.Tensor:
    """ReLU(x) = max(0, x). 음수는 0 으로, 양수는 그대로."""
    return torch.clamp(x, min=0.0)


def gelu(x: torch.Tensor) -> torch.Tensor:
    """GELU(x) = x · Φ(x). Φ 는 표준 정규 분포의 누적 분포 함수: Φ(x) = (1 + erf(x / √2)) / 2."""
    return x * 0.5 * (1.0 + torch.erf(x / math.sqrt(2.0)))


def silu(x: torch.Tensor) -> torch.Tensor:
    """SiLU(x) = x · σ(x). σ 는 시그모이드. Swish 라고도 부른다."""
    return x * torch.sigmoid(x)
# --8<-- [end:activations]


def part1_activations(args):
    print("\n[1] 활성 함수: ReLU · GELU · SiLU")
    x = torch.tensor([-3.0, -1.0, 0.0, 1.0, 3.0])
    print("  x      ", "  ".join(f"{v:8.4f}" for v in x.tolist()))
    for name, fn, ref in [("ReLU", relu, F.relu), ("GELU", gelu, F.gelu), ("SiLU", silu, F.silu)]:
        y = fn(x)
        diff = (y - ref(x)).abs().max().item()
        print(f"  {name}   ", "  ".join(f"{v:8.4f}" for v in y.tolist()), f"  | check: 내장과의 최대 차이 {diff:.1e}")

    fine = torch.linspace(-4, 4, 80001, dtype=torch.float64)
    for name, fn in [("GELU", gelu), ("SiLU", silu)]:
        k = fn(fine).argmin()
        print(f"  {name} 의 최솟값 {fn(fine)[k].item():.4f} (x = {fine[k].item():.4f})")

    # 그림: 함수와 도함수
    xs = torch.linspace(-4, 4, 801, dtype=torch.float64, requires_grad=True)
    fig, axes = plt.subplots(1, 2, figsize=(9.0, 3.4))
    for k, (name, fn) in enumerate([("ReLU", relu), ("GELU", gelu), ("SiLU", silu)]):
        ys = fn(xs)
        (grad,) = torch.autograd.grad(ys.sum(), xs)
        axes[0].plot(xs.detach(), ys.detach(), color=COLORS[k], linestyle=STYLES[k], linewidth=2, label=name)
        axes[1].plot(xs.detach(), grad, color=COLORS[k], linestyle=STYLES[k], linewidth=2, label=name)
    axes[0].set_title("activation f(x)")
    axes[1].set_title("derivative f'(x)")
    for ax in axes:
        ax.axhline(0, color="gray", linewidth=0.6)
        ax.axvline(0, color="gray", linewidth=0.6)
        ax.set_xlabel("x")
        ax.grid(alpha=0.25)
        ax.legend()
    axes[0].set_ylabel("f(x)")
    axes[0].set_ylim(-0.6, 4.1)
    axes[1].set_ylabel("f'(x)")
    fig.tight_layout()
    save_figure(fig, args.fig_dir, "ch04-activations.png")


# ─────────────────────────────────────────────────────────────
# 2. 역전파: 2층 스칼라 신경망
# ─────────────────────────────────────────────────────────────

def part2_backprop(args):
    print("\n[2] 역전파 손계산 ↔ autograd (2층, 스칼라)")
    # --8<-- [start:backprop_manual]
    x, y = 2.0, 1.0  # 입력과 정답
    w1, b1, w2, b2 = 0.5, 0.1, -1.5, 0.2  # 매개변수 네 개

    # 순전파: 값을 왼쪽에서 오른쪽으로
    u = w1 * x + b1  # 1층의 선형 계산
    h = max(u, 0.0)  # ReLU
    y_hat = w2 * h + b2  # 2층
    loss = (y_hat - y) ** 2

    # 역전파: 손실에서 거꾸로, (받은 기울기) × (국소 미분)
    d_yhat = 2 * (y_hat - y)  # ∂L/∂ŷ
    d_w2 = d_yhat * h  # ŷ = w2·h + b2 → ∂ŷ/∂w2 = h
    d_b2 = d_yhat * 1.0  # ∂ŷ/∂b2 = 1
    d_h = d_yhat * w2  # ∂ŷ/∂h = w2
    d_u = d_h * (1.0 if u > 0 else 0.0)  # ReLU 의 미분: u > 0 이면 1, 아니면 0
    d_w1 = d_u * x  # u = w1·x + b1 → ∂u/∂w1 = x
    d_b1 = d_u * 1.0
    # --8<-- [end:backprop_manual]
    print(f"  순전파: u={u:.4f} h={h:.4f} ŷ={y_hat:.4f} L={loss:.4f}")
    print(f"  손계산: dL/dw1={d_w1:.4f} dL/db1={d_b1:.4f} dL/dw2={d_w2:.4f} dL/db2={d_b2:.4f}")

    # --8<-- [start:backprop_autograd]
    params = torch.tensor([w1, b1, w2, b2], dtype=torch.float64, requires_grad=True)
    tw1, tb1, tw2, tb2 = params.unbind()
    t_loss = (tw2 * torch.relu(tw1 * x + tb1) + tb2 - y) ** 2  # 순전파만 적는다
    t_loss.backward()  # 역전파는 autograd 가 한다
    # --8<-- [end:backprop_autograd]
    g = params.grad.tolist()
    print(f"  autograd: dL/dw1={g[0]:.4f} dL/db1={g[1]:.4f} dL/dw2={g[2]:.4f} dL/db2={g[3]:.4f}")
    diff = max(abs(a - b) for a, b in zip(g, [d_w1, d_b1, d_w2, d_b2]))
    print(f"  check: 손계산과 autograd 의 최대 차이 {diff:.1e}")

    lr = 0.01
    w1n, b1n, w2n, b2n = w1 - lr * d_w1, b1 - lr * d_b1, w2 - lr * d_w2, b2 - lr * d_b2
    loss_new = (w2n * max(w1n * x + b1n, 0.0) + b2n - y) ** 2
    print(f"  경사 하강 한 스텝(η={lr}): w1={w1n:.4f} b1={b1n:.4f} w2={w2n:.4f} b2={b2n:.4f} → L={loss_new:.4f} (전 {loss:.4f})")


# ─────────────────────────────────────────────────────────────
# 3. Adam · Adam + L2 · AdamW
# ─────────────────────────────────────────────────────────────

# --8<-- [start:adamw_step]
def adam_step(theta, grad, state, lr=0.01, beta1=0.9, beta2=0.999, eps=1e-8, weight_decay=0.0, decoupled=True):
    """Adam 한 스텝. theta · grad 는 모양이 같은 텐서, state 는 {"m", "v", "n"} 사전.

    weight_decay = λ 를 넣는 방법이 둘이다.
      decoupled=False (Adam + L2): 기울기에 λ·θ 를 더한다 → 감쇠 항도 √v̂ 로 나뉜다.
      decoupled=True  (AdamW)    : 기울기는 그대로 두고, θ 를 따로 (1 − η·λ) 배로 줄인다.
    """
    if weight_decay and not decoupled:
        grad = grad + weight_decay * theta  # L2 벌점 (λ/2)·θ² 의 기울기 λ·θ 를 손실 기울기에 섞는다
    if weight_decay and decoupled:
        theta = theta - lr * weight_decay * theta  # 기울기와 분리된 감쇠: θ ← (1 − η·λ)·θ
    state["n"] += 1
    state["m"] = beta1 * state["m"] + (1 - beta1) * grad  # 1차 모멘트: 기울기의 지수 이동 평균
    state["v"] = beta2 * state["v"] + (1 - beta2) * grad**2  # 2차 모멘트: 기울기 제곱의 지수 이동 평균
    m_hat = state["m"] / (1 - beta1 ** state["n"])  # 0 에서 시작한 탓에 작게 나온 것을 보정
    v_hat = state["v"] / (1 - beta2 ** state["n"])
    return theta - lr * m_hat / (v_hat.sqrt() + eps)
# --8<-- [end:adamw_step]


def part3_adamw(args):
    print("\n[3] Adam · Adam+L2 · AdamW 한 스텝 (θ=1, η=0.01, λ=0.1)")
    grad = torch.tensor([10.0, 0.001], dtype=torch.float64)  # 기울기가 큰 가중치와 작은 가중치
    for name, wd, decoupled in [("Adam (감쇠 없음)", 0.0, True), ("Adam + L2      ", 0.1, False), ("AdamW          ", 0.1, True)]:
        theta = torch.ones(2, dtype=torch.float64)
        state = {"m": torch.zeros(2, dtype=torch.float64), "v": torch.zeros(2, dtype=torch.float64), "n": 0}
        theta = adam_step(theta, grad, state, weight_decay=wd, decoupled=decoupled)
        print(f"  {name}: 기울기 10 인 가중치 → {theta[0].item():.6f}, 기울기 0.001 인 가중치 → {theta[1].item():.6f}")

    # torch.optim 과 대조: 손실 L = Σ c·θ² 를 20 스텝
    torch.manual_seed(args.seed)
    c = torch.rand(5, dtype=torch.float64) * 3
    start = torch.randn(5, dtype=torch.float64)
    for name, decoupled, opt_cls in [("Adam+L2", False, torch.optim.Adam), ("AdamW", True, torch.optim.AdamW)]:
        mine = start.clone()
        state = {"m": torch.zeros(5, dtype=torch.float64), "v": torch.zeros(5, dtype=torch.float64), "n": 0}
        ref = start.clone().requires_grad_(True)
        opt = opt_cls([ref], lr=0.01, weight_decay=0.1)
        for _ in range(20):
            mine = adam_step(mine, 2 * c * mine, state, weight_decay=0.1, decoupled=decoupled)
            opt.zero_grad()
            (c * ref**2).sum().backward()
            opt.step()
        print(f"  check: 직접 구현한 {name} 20 스텝 vs torch.optim 최대 차이 {(mine - ref.detach()).abs().max().item():.1e}")


# ─────────────────────────────────────────────────────────────
# 4. 시그모이드 · BCE · 소프트맥스
# ─────────────────────────────────────────────────────────────

# --8<-- [start:sigmoid_bce]
def sigmoid(z: torch.Tensor) -> torch.Tensor:
    """σ(z) = 1 / (1 + e^(−z)). 로짓(실수 전체)을 확률(0 – 1)로."""
    return 1.0 / (1.0 + torch.exp(-z))


def bce_naive(z: torch.Tensor, t: torch.Tensor) -> torch.Tensor:
    """정의 그대로: 먼저 p = σ(z) 를 만들고 −t·log p − (1 − t)·log(1 − p). |z| 가 크면 log(0) 이 나온다."""
    p = sigmoid(z)
    return -t * torch.log(p) - (1 - t) * torch.log(1 - p)


def bce_with_logits(z: torch.Tensor, t: torch.Tensor) -> torch.Tensor:
    """로짓에서 바로 계산하는 BCE: max(z, 0) − z·t + log(1 + e^(−|z|)). 원소마다의 손실을 돌려준다.

    z: 로짓, t: 목표(0 또는 1, 또는 0 – 1 사이의 부드러운 목표). 모양은 같아야 하고 무엇이든 된다.
    e 의 지수가 늘 0 이하(−|z|)이므로 넘치지 않고, log1p 는 1 + (아주 작은 수) 의 로그를 정확히 계산한다.
    max(z, 0) 은 (z + |z|) / 2 로 적었다. 값은 같고, 꺾이는 점 z = 0 에서도 autograd 가 옳은 기울기(p − t)를 준다.
    """
    return 0.5 * (z + z.abs()) - z * t + torch.log1p(torch.exp(-z.abs()))
# --8<-- [end:sigmoid_bce]


# --8<-- [start:softmax_ce]
def softmax_cross_entropy(z: torch.Tensor, label: torch.Tensor) -> torch.Tensor:
    """소프트맥스 교차 엔트로피. z: (N, K) 로짓, label: (N,) 정답 클래스 번호 → (N,) 손실.

    log p_k = z_k − log Σ_j e^(z_j). 가장 큰 로짓을 먼저 빼 두면 e 의 지수가 0 이하가 되어 넘치지 않는다.
    """
    z = z - z.max(dim=1, keepdim=True).values
    log_p = z - torch.log(torch.exp(z).sum(dim=1, keepdim=True))  # (N, K)
    return -log_p.gather(1, label[:, None]).squeeze(1)  # 정답 클래스의 −log p 만 고른다
# --8<-- [end:softmax_ce]


def part4_bce(args):
    print("\n[4] 시그모이드 · BCE · 소프트맥스")
    z = torch.tensor([-4.5951, -2.0, 0.0, 2.0, 4.5951], dtype=torch.float64)
    p = sigmoid(z)
    print("  z        ", "  ".join(f"{v:8.4f}" for v in z.tolist()))
    print("  σ(z)     ", "  ".join(f"{v:8.4f}" for v in p.tolist()))
    print("  σ(z)+σ(−z)", "  ".join(f"{v:8.4f}" for v in (p + sigmoid(-z)).tolist()))
    print("  log(p/(1−p))", "  ".join(f"{v:8.4f}" for v in torch.log(p / (1 - p)).tolist()), " ← 로짓이 되돌아온다")

    # 손계산 예: z = 2
    z2 = torch.tensor(2.0, dtype=torch.float64)
    for target in [1.0, 0.0]:
        t = torch.tensor(target, dtype=torch.float64)
        print(f"  z=2, y={target:.0f}: p={sigmoid(z2).item():.4f}  BCE(정의)={bce_naive(z2, t).item():.4f}  BCE(로짓에서 바로)={bce_with_logits(z2, t).item():.4f}")

    # --8<-- [start:bce_checks]
    torch.manual_seed(args.seed)
    logits = (torch.randn(1000, dtype=torch.float64) * 5).requires_grad_(True)
    targets = torch.randint(0, 2, (1000,)).double()
    mine = bce_with_logits(logits, targets)
    ref = F.binary_cross_entropy_with_logits(logits, targets, reduction="none")
    print(f"  check: bce_with_logits vs F.binary_cross_entropy_with_logits 최대 차이 {(mine - ref).abs().max().item():.1e}")
    mine.sum().backward()  # autograd 가 구한 ∂L/∂z
    by_formula = torch.sigmoid(logits.detach()) - targets  # 손으로 유도한 p − y
    print(f"  check: 기울기 ∂L/∂z vs (p − y) 최대 차이 {(logits.grad - by_formula).abs().max().item():.1e}")
    # --8<-- [end:bce_checks]

    # 수치 안정: float32 에서 정의 그대로 계산하면 무너지는 자리
    for zv, tv in [(40.0, 0.0), (-110.0, 1.0)]:
        zf, tf = torch.tensor(zv), torch.tensor(tv)  # float32
        print(f"  float32, z={zv:.0f}, y={tv:.0f}: 정의 그대로 = {bce_naive(zf, tf).item()}, 로짓에서 바로 = {bce_with_logits(zf, tf).item():.4f}")

    # --8<-- [start:soft_target]
    # 부드러운 목표 t 일 때 손실이 가장 작아지는 확률 p 를 촘촘한 격자에서 찾는다
    grid = torch.linspace(0.001, 0.999, 999, dtype=torch.float64)  # p = 0.001, 0.002, …, 0.999
    for t in [0.2, 0.7, 1.0]:
        loss = -t * torch.log(grid) - (1 - t) * torch.log(1 - grid)
        best = grid[loss.argmin()].item()
        print(f"  부드러운 목표 t={t}: 손실이 최소인 p={best:.3f}, 그때의 손실 {loss.min().item():.4f}")
    # --8<-- [end:soft_target]
    zt = torch.tensor(0.0, dtype=torch.float64, requires_grad=True)
    bce_with_logits(zt, torch.tensor(0.7, dtype=torch.float64)).backward()
    print(f"  check: z=0(p=0.5), t=0.7 에서 ∂L/∂z = {zt.grad.item():.4f} (p − t = −0.2)")

    # 소프트맥스
    z3 = torch.tensor([[2.0, 1.0, 0.0]], dtype=torch.float64)
    p3 = torch.softmax(z3, dim=1)[0]
    ce = softmax_cross_entropy(z3, torch.tensor([0]))
    ref = F.cross_entropy(z3, torch.tensor([0]), reduction="none")
    print(f"  소프트맥스: z=(2, 1, 0) → p=({p3[0]:.4f}, {p3[1]:.4f}, {p3[2]:.4f}) 합 {p3.sum().item():.4f}, 정답 0번 CE={ce.item():.4f}")
    print(f"  시그모이드 따로: σ(z)=({sigmoid(z3)[0, 0]:.4f}, {sigmoid(z3)[0, 1]:.4f}, {sigmoid(z3)[0, 2]:.4f}) 합 {sigmoid(z3).sum().item():.4f}")
    zr = torch.randn(64, 7, dtype=torch.float64) * 4
    lr_ = torch.randint(0, 7, (64,))
    diff = (softmax_cross_entropy(zr, lr_) - F.cross_entropy(zr, lr_, reduction="none")).abs().max().item()
    print(f"  check: softmax_cross_entropy vs F.cross_entropy 최대 차이 {max(diff, (ce - ref).abs().item()):.1e}")
    two = torch.softmax(torch.tensor([1.3, -0.4], dtype=torch.float64), dim=0)[0].item()
    print(f"  check: 2클래스 소프트맥스 p_0={two:.6f} = σ(z_0 − z_1)={torch.sigmoid(torch.tensor(1.7, dtype=torch.float64)).item():.6f}")


# ─────────────────────────────────────────────────────────────
# 5. 포컬 손실 · 사전 확률 편향
# ─────────────────────────────────────────────────────────────

# --8<-- [start:focal_loss]
def focal_loss_elementwise(z: torch.Tensor, t: torch.Tensor, alpha: float = 0.25, gamma: float = 2.0) -> torch.Tensor:
    """원소마다의 포컬 손실 FL = −α_t · (1 − p_t)^γ · log(p_t). z: 로짓, t: 0/1 목표 (모양은 같고 무엇이든).

    공식 구현(rfdetr/models/criterion.py 의 sigmoid_focal_loss)과 같은 순서로 계산한다.
    """
    p = torch.sigmoid(z)
    ce = bce_with_logits(z, t)  # −log(p_t): 수치 안정 형태의 BCE 를 그대로 쓴다
    p_t = p * t + (1 - p) * (1 - t)  # 정답 쪽 확률: 양성이면 p, 음성이면 1 − p
    loss = ce * (1 - p_t) ** gamma  # 쉬운 칸(p_t 가 1 에 가까운 칸)의 손실을 줄이는 조절 인자
    if alpha >= 0:  # 음수를 주면 α 균형을 끈다
        alpha_t = alpha * t + (1 - alpha) * (1 - t)  # 양성이면 α, 음성이면 1 − α
        loss = alpha_t * loss
    return loss


def sigmoid_focal_loss(inputs: torch.Tensor, targets: torch.Tensor, num_boxes: float, alpha: float = 0.25,
                       gamma: float = 2.0) -> torch.Tensor:
    """모든 칸의 포컬 손실을 더해 양성(객체) 수로 나눈다.

    음성 칸까지 센 전체 칸 수로 나누면 값이 0 에 가까워져 버리므로, 양성 수로 나누는 것이 탐지기의 관례다.
    공식 구현은 (B, Q, K) 로짓에 대해 `loss.mean(1).sum() / num_boxes` 를 돌려주고 부르는 쪽에서 Q 를 곱한다.
    질의 축으로 평균 낸 뒤 Q 를 곱하면 합이므로, 결국 이 함수와 같은 값(전체 합 / num_boxes)이다.
    """
    return focal_loss_elementwise(inputs, targets, alpha, gamma).sum() / num_boxes
# --8<-- [end:focal_loss]


# --8<-- [start:focal_grad]
def focal_grad_formula(z: torch.Tensor, t: torch.Tensor, alpha: float = 0.25, gamma: float = 2.0) -> torch.Tensor:
    """본문에서 유도한 ∂FL/∂z = ± α_t · (1 − p_t)^γ · (γ · p_t · log p_t + p_t − 1). 부호는 양성 +, 음성 −."""
    p = torch.sigmoid(z)
    p_t = p * t + (1 - p) * (1 - t)
    alpha_t = alpha * t + (1 - alpha) * (1 - t)
    sign = 2 * t - 1  # 양성 +1, 음성 −1
    return sign * alpha_t * (1 - p_t) ** gamma * (gamma * p_t * torch.log(p_t) + p_t - 1)
# --8<-- [end:focal_grad]


# --8<-- [start:prior_bias]
def prior_bias(prior_prob: float = 0.01) -> float:
    """σ(b) = π 가 되는 편향 b = −log((1 − π) / π). π = 0.01 이면 −4.5951."""
    return -math.log((1 - prior_prob) / prior_prob)
# --8<-- [end:prior_bias]


def part5_focal(args):
    print("\n[5] 포컬 손실")
    # 손계산 표: p_t 에 따른 CE 와 포컬 손실 (α 균형 없이, γ = 2)
    print("  p_t      CE=−log p_t   (1−p_t)^2    FL(γ=2)     CE/FL")
    for p_t in [0.1, 0.5, 0.9, 0.968, 0.99]:
        ce = -math.log(p_t)
        mod = (1 - p_t) ** 2
        print(f"  {p_t:<6}   {ce:9.5f}   {mod:10.6f}   {ce * mod:10.7f}   {1 / mod:8.1f}")

    # --8<-- [start:focal_checks]
    torch.manual_seed(args.seed)
    z = (torch.randn(4, 300, 80, dtype=torch.float64) * 3).requires_grad_(True)  # (B, Q, K) 로짓
    t = (torch.rand(4, 300, 80) < 0.01).double()  # 양성 약 1%
    p = torch.sigmoid(z.detach())
    p_t = torch.where(t == 1, p, 1 - p)
    alpha_t = torch.where(t == 1, torch.tensor(0.25, dtype=torch.float64), torch.tensor(0.75, dtype=torch.float64))
    by_definition = -alpha_t * (1 - p_t) ** 2 * torch.log(p_t)  # 정의 FL = −α_t (1 − p_t)^γ log p_t 를 그대로
    mine = focal_loss_elementwise(z, t, alpha=0.25, gamma=2.0)
    print(f"  check: focal_loss_elementwise vs 정의식 최대 차이 {(mine - by_definition).abs().max().item():.1e}")
    plain = focal_loss_elementwise(z, t, alpha=-1, gamma=0.0)  # γ = 0, α 균형 끔 → BCE 여야 한다
    ref = F.binary_cross_entropy_with_logits(z, t, reduction="none")
    print(f"  check: γ=0 · α 끔 → F.binary_cross_entropy_with_logits 와의 최대 차이 {(plain - ref).abs().max().item():.1e}")
    mine.sum().backward()
    diff = (z.grad - focal_grad_formula(z.detach(), t)).abs().max().item()
    print(f"  check: autograd 기울기 vs 유도한 기울기 식 최대 차이 {diff:.1e}")
    # --8<-- [end:focal_checks]
    for zv, tv in [(0.0, 1.0), (2.0, 1.0), (-2.0, 0.0), (2.0, 0.0)]:
        zz, tt = torch.tensor(zv, dtype=torch.float64), torch.tensor(tv, dtype=torch.float64)
        print(f"  z={zv:+.0f}, y={tv:.0f}: p={torch.sigmoid(zz).item():.4f}  BCE={bce_with_logits(zz, tt).item():.4f}  "
              f"FL={focal_loss_elementwise(zz, tt).item():.5f}  ∂BCE/∂z={(torch.sigmoid(zz) - tt).item():+.4f}  "
              f"∂FL/∂z={focal_grad_formula(zz, tt).item():+.5f}")

    # --8<-- [start:imbalance_count]
    # 질의 300개 × 클래스 80개 = 24,000칸, 객체 10개. 양성은 아직 어려워 p = 0.3, 음성은 쉬워서 p = p_neg 라고 하자.
    cells, num_pos = 300 * 80, 10
    num_neg = cells - num_pos
    print("  24,000칸 · 양성 10칸(p=0.3) · 음성 23,990칸(p=p_neg) 의 손실 합")
    print("  p_neg   BCE: 양성 합  음성 합  음성 몫 |  포컬: 양성 합  음성 합  음성 몫")
    for p_neg in [0.1, 0.05, 0.02, 0.01]:
        zp = torch.logit(torch.tensor(0.3, dtype=torch.float64))
        zn = torch.logit(torch.tensor(p_neg, dtype=torch.float64))
        one, zero = torch.tensor(1.0, dtype=torch.float64), torch.tensor(0.0, dtype=torch.float64)
        bce_pos = num_pos * bce_with_logits(zp, one).item()
        bce_neg = num_neg * bce_with_logits(zn, zero).item()
        fl_pos = num_pos * focal_loss_elementwise(zp, one).item()
        fl_neg = num_neg * focal_loss_elementwise(zn, zero).item()
        print(f"  {p_neg:<5}   {bce_pos:9.2f}  {bce_neg:8.2f}  {100 * bce_neg / (bce_pos + bce_neg):5.1f}%  |"
              f"  {fl_pos:10.3f}  {fl_neg:8.3f}  {100 * fl_neg / (fl_pos + fl_neg):5.1f}%")
    # --8<-- [end:imbalance_count]

    # --8<-- [start:prior_init]
    # 학습을 시작하는 순간의 손실: 24,000칸 모두 같은 확률을 낸다고 보고, 양성 수(10)로 나눈 값
    print(f"  사전 확률 편향: π=0.01 → b={prior_bias(0.01):.4f}, σ(b)={torch.sigmoid(torch.tensor(prior_bias(0.01))).item():.4f}")
    targets = torch.zeros(300, 80, dtype=torch.float64)
    targets[:num_pos, 0] = 1.0  # 양성 10칸
    for name, bias in [("b = 0 (p = 0.5)       ", 0.0), ("b = −4.5951 (p = 0.01)", prior_bias(0.01))]:
        logits = torch.full((300, 80), bias, dtype=torch.float64)
        bce = bce_with_logits(logits, targets).sum().item() / num_pos
        focal = sigmoid_focal_loss(logits, targets, num_pos).item()
        print(f"  초기 손실 {name}: BCE {bce:9.2f}   포컬 {focal:8.3f}")
    # --8<-- [end:prior_init]

    # 그림: 시그모이드, p_t 에 따른 손실, 로짓에 대한 기울기 크기
    fig, axes = plt.subplots(1, 3, figsize=(13.0, 3.7))
    zs = torch.linspace(-8, 8, 801, dtype=torch.float64)
    axes[0].plot(zs, torch.sigmoid(zs), color=COLORS[0], linewidth=2)
    b = prior_bias(0.01)
    axes[0].plot([0, b], [0.5, 0.01], "o", color=COLORS[1])
    axes[0].annotate("z = 0, p = 0.5", (0, 0.5), textcoords="offset points", xytext=(8, -6))
    axes[0].annotate("z = -4.595, p = 0.01", (b, 0.01), textcoords="offset points", xytext=(-12, 12))
    axes[0].set_xlabel("logit z")
    axes[0].set_ylabel("probability p")
    axes[0].set_title("sigmoid: p = 1 / (1 + exp(-z))")
    pts = torch.linspace(0.001, 0.999, 999, dtype=torch.float64)
    one = torch.ones_like(pts)
    for k, gamma in enumerate([0.0, 0.5, 1.0, 2.0, 5.0]):
        loss = -((1 - pts) ** gamma) * torch.log(pts)
        grad = focal_grad_formula(torch.logit(pts), one, alpha=1.0, gamma=gamma).abs()
        label = "gamma = 0 (BCE)" if gamma == 0 else f"gamma = {gamma:g}"
        axes[1].plot(pts, loss, color=COLORS[k], linestyle=STYLES[k], linewidth=2, label=label)
        axes[2].plot(pts, grad, color=COLORS[k], linestyle=STYLES[k], linewidth=2, label=label)
    axes[1].set_ylim(0, 5)
    axes[1].set_xlabel("probability of the correct answer, p_t")
    axes[1].set_ylabel("loss")
    axes[1].set_title("focal loss  -(1 - p_t)^gamma log(p_t)")
    axes[1].axvspan(0.6, 1.0, color="gray", alpha=0.12)
    axes[1].text(0.8, 2.6, "easy\nexamples", ha="center", fontsize=9)
    axes[2].set_xlabel("probability of the correct answer, p_t")
    axes[2].set_ylabel("|d loss / d logit|")
    axes[2].set_title("gradient magnitude w.r.t. the logit")
    for ax in axes:
        ax.grid(alpha=0.25)
    axes[1].legend(fontsize=8)
    axes[2].legend(fontsize=8)
    fig.tight_layout()
    save_figure(fig, args.fig_dir, "ch04-losses.png")


# ─────────────────────────────────────────────────────────────
# 6. 정규화 층
# ─────────────────────────────────────────────────────────────

def part6_norm(args, n_images: int, n_batches: int):
    print("\n[6] 배치 정규화 · 층 정규화")
    # --8<-- [start:norm_manual]
    x = torch.tensor([[1.0, 2.0, 3.0], [3.0, 6.0, 9.0]])  # (B=2, C=3): 그림 두 장, 특징 세 개

    # 배치 정규화: 특징(열)마다, 배치 축(dim=0)으로 평균 · 분산
    mu_b, var_b = x.mean(dim=0), x.var(dim=0, unbiased=False)  # (3,), (3,)
    bn_manual = (x - mu_b) / torch.sqrt(var_b + 1e-5)

    # 층 정규화: 표본(행)마다, 특징 축(dim=1)으로 평균 · 분산
    mu_l, var_l = x.mean(dim=1, keepdim=True), x.var(dim=1, unbiased=False, keepdim=True)  # (2, 1), (2, 1)
    ln_manual = (x - mu_l) / torch.sqrt(var_l + 1e-5)

    bn, ln = nn.BatchNorm1d(3), nn.LayerNorm(3)  # 처음에는 크기 조절 1, 이동 0 → 정규화만 한다
    bn.train()
    print(f"  check: 배치 정규화 손계산 vs nn.BatchNorm1d 최대 차이 {(bn(x) - bn_manual).abs().max().item():.1e}")
    print(f"  check: 층 정규화 손계산 vs nn.LayerNorm 최대 차이 {(ln(x) - ln_manual).abs().max().item():.1e}")
    # --8<-- [end:norm_manual]
    print("  배치 평균", mu_b.tolist(), "배치 분산", var_b.tolist())
    print("  배치 정규화 출력", [[round(v, 4) for v in row] for row in bn_manual.tolist()])
    print("  행 평균", mu_l.flatten().tolist(), "행 분산", [round(v, 4) for v in var_l.flatten().tolist()])
    print("  층 정규화 출력  ", [[round(v, 4) for v in row] for row in ln_manual.tolist()])
    # 학습 모드에서 한 번 지나간 뒤의 이동 통계와, 추론 모드 출력
    print("  이동 평균", [round(v, 4) for v in bn.running_mean.tolist()], "이동 분산", [round(v, 4) for v in bn.running_var.tolist()])
    bn.eval()
    print("  추론 모드 출력  ", [[round(v, 4) for v in row] for row in bn(x).tolist()])

    # --8<-- [start:norm_wobble]
    # 도형 세상 그림을 고정된 무작위 합성곱(16×16 패치마다 특징 8개)에 통과시킨 특징 맵으로 통계의 흔들림을 잰다
    dataset = ShapesDataset(n_images, seed=0)
    torch.manual_seed(args.seed)
    conv = nn.Conv2d(3, 8, kernel_size=16, stride=16)
    with torch.no_grad():
        feats = torch.relu(conv(dataset.images.float() / 255.0))  # (n, 8, 6, 6)
    pop_mean = feats.mean(dim=(0, 2, 3))  # (8,) 전체 데이터에서의 채널 평균: 배치 통계가 맞혀야 할 값
    pop_std = feats.std(dim=(0, 2, 3))
    probe = feats[0]  # 늘 배치의 첫 자리에 넣을 그림 한 장 (8, 6, 6)
    generator = torch.Generator().manual_seed(args.seed)
    results = {}
    for batch_size in [2, 4, 16, 64]:
        means, stds, bn_out, ln_out = [], [], [], []
        for _ in range(n_batches):
            batch = feats[torch.randint(0, len(feats), (batch_size,), generator=generator)]  # 무작위 배치 (B, 8, 6, 6)
            means.append(batch.mean(dim=(0, 2, 3)))  # 배치 정규화가 쓰는 통계: 채널마다 (B, H, W) 축 평균
            stds.append(batch.std(dim=(0, 2, 3), unbiased=False))
            batch = torch.cat([probe[None], batch[1:]])  # 첫 자리를 probe 로 바꾼 배치: 함께 들어간 그림만 매번 다르다
            mu, sd = batch.mean(dim=(0, 2, 3)), batch.std(dim=(0, 2, 3), unbiased=False)
            bn_out.append((probe - mu[:, None, None]) / (sd[:, None, None] + 1e-5))  # probe 의 배치 정규화 출력
            # 층 정규화(RF-DETR 프로젝터 방식): 위치마다 채널 축(dim=0)으로 평균 · 분산 → 다른 그림과 무관
            ln_out.append((probe - probe.mean(dim=0)) / (probe.std(dim=0, unbiased=False) + 1e-5))
        means, stds = torch.stack(means), torch.stack(stds)  # (n_batches, 8)
        results[batch_size] = {
            "mean_wobble": (means.std(dim=0) / pop_std).mean().item(),  # 배치 평균의 흔들림 (전체 표준편차 단위)
            "std_wobble": (stds.std(dim=0) / pop_std).mean().item(),  # 배치 표준편차의 흔들림
            "bn_out_wobble": torch.stack(bn_out).std(dim=0).mean().item(),  # 같은 그림의 출력이 배치마다 달라지는 정도
            "ln_out_wobble": torch.stack(ln_out).std(dim=0).mean().item(),
            "means_ch0": (means[:, 0] - pop_mean[0]) / pop_std[0],
        }
    # --8<-- [end:norm_wobble]
    print(f"  특징 맵 {tuple(feats.shape)}, 배치 {n_batches}개씩")
    print("  배치 크기  배치 평균의 흔들림  배치 표준편차의 흔들림  같은 그림의 출력 흔들림(BN)  (LN)")
    for batch_size, r in results.items():
        print(f"  {batch_size:>6}    {r['mean_wobble']:14.4f}    {r['std_wobble']:16.4f}    {r['bn_out_wobble']:18.4f}    {r['ln_out_wobble']:.4f}")
    ratio = results[2]["mean_wobble"] / results[64]["mean_wobble"]
    print(f"  배치 2 와 64 의 평균 흔들림 비 {ratio:.2f} (√(64/2) = {math.sqrt(32):.2f})")

    fig, axes = plt.subplots(1, 2, figsize=(10.0, 3.6))
    bins = np.linspace(-0.6, 0.6, 49)
    for k, batch_size in enumerate([2, 64]):
        axes[0].hist(results[batch_size]["means_ch0"].numpy(), bins=bins, color=COLORS[k], alpha=0.65,
                     label=f"batch size {batch_size}", hatch=["//", ""][k], edgecolor="white")
    axes[0].axvline(0, color="black", linewidth=1, linestyle="--")
    axes[0].set_xlabel("(batch mean - dataset mean) / dataset std, channel 0")
    axes[0].set_ylabel("number of batches")
    axes[0].set_title("batch statistics wobble")
    axes[0].legend()
    sizes = list(results)
    xpos = np.arange(len(sizes))
    axes[1].bar(xpos - 0.2, [results[s]["bn_out_wobble"] for s in sizes], width=0.4, color=COLORS[1], hatch="//",
                edgecolor="white", label="batch norm")
    axes[1].bar(xpos + 0.2, [results[s]["ln_out_wobble"] for s in sizes], width=0.4, color=COLORS[0], label="layer norm")
    axes[1].set_xticks(xpos)
    axes[1].set_xticklabels([str(s) for s in sizes])
    axes[1].set_xlabel("batch size")
    axes[1].set_ylabel("std of the same image's output\nacross batches")
    axes[1].set_title("output of one fixed image")
    axes[1].legend()
    for ax in axes:
        ax.grid(alpha=0.25)
    fig.tight_layout()
    save_figure(fig, args.fig_dir, "ch04-norm.png")


# ─────────────────────────────────────────────────────────────
# 7. 잔차 연결
# ─────────────────────────────────────────────────────────────

# --8<-- [start:residual_grad]
def first_layer_gradient(depth: int, residual: bool, width: int = 64, seed: int = 0) -> float:
    """깊이 depth 인 MLP 에서, 출력의 합을 첫 층 입력으로 미분한 기울기의 크기(노름).

    residual=False: x ← tanh(Linear(x))          (층을 그냥 쌓음)
    residual=True : x ← x + tanh(Linear(x))      (잔차 연결)
    """
    torch.manual_seed(seed)
    layers = [nn.Linear(width, width) for _ in range(depth)]
    x0 = torch.randn(16, width, requires_grad=True)  # (16, width)
    x = x0
    for layer in layers:
        fx = torch.tanh(layer(x))
        x = x + fx if residual else fx
    x.sum().backward()
    return x0.grad.norm().item()
# --8<-- [end:residual_grad]


def part7_residual(args):
    print("\n[7] 잔차 연결과 기울기")
    print("  층 수   그냥 쌓음       잔차 연결")
    for depth in [1, 5, 10, 20, 40]:
        plain = first_layer_gradient(depth, residual=False, seed=args.seed)
        res = first_layer_gradient(depth, residual=True, seed=args.seed)
        print(f"  {depth:>4}   {plain:12.3e}   {res:12.3e}")


# ─────────────────────────────────────────────────────────────
# 8. 합성곱
# ─────────────────────────────────────────────────────────────

def part8_conv(args):
    print("\n[8] 합성곱 출력 크기 · 패치 나누기")
    # --8<-- [start:conv_shapes]
    def conv_out(n_in: int, kernel: int, stride: int = 1, padding: int = 0) -> int:
        """출력 크기 = ⌊(n_in − F + 2P) / S⌋ + 1."""
        return (n_in - kernel + 2 * padding) // stride + 1

    x = torch.randn(2, 3, 96, 96)  # (B, C, H, W): 도형 세상 그림 두 장
    for kernel, stride, padding in [(3, 1, 1), (3, 2, 1), (1, 1, 0), (16, 16, 0)]:
        conv = nn.Conv2d(3, 8, kernel_size=kernel, stride=stride, padding=padding)
        n_params = sum(p.numel() for p in conv.parameters())
        print(f"  커널 {kernel:>2} · 스트라이드 {stride:>2} · 패딩 {padding}: 공식 {conv_out(96, kernel, stride, padding):>2} → 실제 {tuple(conv(x).shape)}, 매개변수 {n_params}")
    up = nn.ConvTranspose2d(8, 8, kernel_size=2, stride=2)  # 전치 합성곱: (n − 1)·S − 2P + F = 2n
    print(f"  전치 합성곱 커널 2 · 스트라이드 2: {tuple(torch.randn(2, 8, 6, 6).shape)} → {tuple(up(torch.randn(2, 8, 6, 6)).shape)}")
    # --8<-- [end:conv_shapes]

    # --8<-- [start:patchify]
    # 스트라이드 = 커널 = 16 인 합성곱은 "16×16 패치로 자르고, 패치마다 같은 선형 층" 과 같다
    conv = nn.Conv2d(3, 8, kernel_size=16, stride=16)
    by_conv = conv(x)  # (2, 8, 6, 6)
    patches = x.reshape(2, 3, 6, 16, 6, 16).permute(0, 2, 4, 1, 3, 5).reshape(2, 36, 3 * 16 * 16)  # (2, 36, 768)
    linear_w = conv.weight.reshape(8, 3 * 16 * 16)  # 커널을 펴면 선형 층의 가중치 (8, 768)
    by_linear = patches @ linear_w.T + conv.bias  # (2, 36, 8): 패치 36개 각각에 같은 선형 층
    by_linear = by_linear.reshape(2, 6, 6, 8).permute(0, 3, 1, 2)  # (2, 8, 6, 6) 으로 되돌려 비교
    print(f"  check: 패치 나누기 + 선형 층 vs 합성곱(커널 16 · 스트라이드 16) 최대 차이 {(by_conv - by_linear).abs().max().item():.1e}")
    # --8<-- [end:patchify]
    conv1 = nn.Conv2d(3, 8, kernel_size=1)
    by_linear1 = x.permute(0, 2, 3, 1) @ conv1.weight.reshape(8, 3).T + conv1.bias  # 위치마다 Linear(3, 8)
    print(f"  check: 1×1 합성곱 vs 위치마다의 선형 층 최대 차이 {(conv1(x) - by_linear1.permute(0, 3, 1, 2)).abs().max().item():.1e}")


# ─────────────────────────────────────────────────────────────
# 9. 불균형 실험: 도형 중심이 있는 격자 칸 찾기
# ─────────────────────────────────────────────────────────────

GRID = 12  # 96×96 그림을 12×12 칸(칸 하나 8×8 픽셀)으로 나눈다


# --8<-- [start:center_data]
def center_targets(dataset: ShapesDataset, grid: int = GRID) -> torch.Tensor:
    """그림마다 (클래스 3, 격자 12, 격자 12) 의 0/1 목표. "클래스 k 인 도형의 중심이 이 칸에 있는가".

    한 그림의 칸은 3 × 12 × 12 = 432개이고 양성은 도형 수(1 – 4개)뿐이다 → 양성 약 0.6%.
    """
    targets = torch.zeros(len(dataset), NUM_CLASSES, grid, grid)
    for i, target in enumerate(dataset.targets):
        for (cx, cy, _w, _h), cls in zip(target["boxes"].tolist(), target["labels"].tolist()):
            col, row = min(int(cx * grid), grid - 1), min(int(cy * grid), grid - 1)  # 중심이 떨어지는 칸
            targets[i, cls, row, col] = 1.0
    return targets
# --8<-- [end:center_data]


# --8<-- [start:center_model]
class CenterGridNet(nn.Module):
    """그림 (B, 3, 96, 96) → 칸마다 · 클래스마다의 로짓 (B, 3, 12, 12). 클래스마다 독립인 시그모이드를 쓴다.

    prior_prob 을 주면 마지막 층의 편향을 b = −log((1 − π)/π) 로 둔다 (RF-DETR 의 class_embed 와 같은 초기화).
    주지 않으면 PyTorch 의 기본 초기화(0 근처의 작은 값)를 그대로 쓴다 → 처음 예측이 0.5 근처.
    """

    def __init__(self, num_classes: int = NUM_CLASSES, width: int = 32, prior_prob: float | None = None):
        super().__init__()
        self.body = nn.Sequential(
            nn.Conv2d(3, width, 3, stride=2, padding=1), nn.ReLU(),  # (B, 32, 48, 48)
            nn.Conv2d(width, 2 * width, 3, stride=2, padding=1), nn.ReLU(),  # (B, 64, 24, 24)
            nn.Conv2d(2 * width, 2 * width, 3, stride=2, padding=1), nn.ReLU(),  # (B, 64, 12, 12)
            nn.Conv2d(2 * width, 2 * width, 3, padding=1), nn.ReLU(),  # 12×12 를 유지하며 주변을 더 본다
            nn.Conv2d(2 * width, 2 * width, 3, padding=1), nn.ReLU(),
        )
        self.head = nn.Conv2d(2 * width, num_classes, kernel_size=1)  # 1×1 합성곱 = 칸마다의 선형 분류 머리
        if prior_prob is not None:
            nn.init.constant_(self.head.bias, prior_bias(prior_prob))

    def forward(self, images: torch.Tensor) -> torch.Tensor:
        return self.head(self.body(images))
# --8<-- [end:center_model]


# --8<-- [start:center_metrics]
@torch.no_grad()
def cell_metrics(logits: torch.Tensor, targets: torch.Tensor, threshold: float = 0.5) -> dict:
    """모든 칸을 한 줄로 펴서 잰 양성 재현율 · 정밀도(문턱값 0.5)와 평균 정밀도(AP, 문턱값과 무관).

    AP: 칸을 점수가 높은 순으로 늘어놓고, 양성 칸이 나올 때마다 그때까지의 정밀도를 적어 평균 낸 값.
    """
    scores, labels = torch.sigmoid(logits).flatten(), targets.flatten() > 0.5
    predicted = scores >= threshold
    tp = (predicted & labels).sum().item()
    order = scores.argsort(descending=True)
    hits = labels[order].double()
    precision_at = hits.cumsum(0) / torch.arange(1, len(hits) + 1, device=hits.device)
    return {
        "recall": tp / max(labels.sum().item(), 1),
        "precision": tp / max(predicted.sum().item(), 1),
        "ap": ((precision_at * hits).sum() / hits.sum()).item(),
        "mean_p": scores.mean().item(),
    }
# --8<-- [end:center_metrics]


# --8<-- [start:center_train]
def train_center(train_x, train_t, val_x, val_t, loss_name: str, prior_prob, optimizer_name: str, epochs: int,
                 seed: int, batch_size: int = 32) -> dict:
    """설정 하나를 학습한다. 돌려주는 값: 스텝마다의 손실, 에폭마다의 검증 지표(0번은 학습 전), 모델."""
    torch.manual_seed(seed)  # 설정이 달라도 몸통의 초기 가중치와 배치 순서는 같다
    model = CenterGridNet(prior_prob=prior_prob).to(train_x.device)
    if optimizer_name == "adamw":
        optimizer = torch.optim.AdamW(model.parameters(), lr=1e-3, weight_decay=1e-4)
    else:
        optimizer = torch.optim.SGD(model.parameters(), lr=0.01, momentum=0.9, weight_decay=1e-4)

    def loss_fn(logits, targets):
        num_pos = targets.sum().clamp(min=1.0)  # 이 배치의 양성(도형) 수
        if loss_name == "bce":
            return bce_with_logits(logits, targets).sum() / num_pos
        return sigmoid_focal_loss(logits, targets, num_pos, alpha=0.25, gamma=2.0)

    def evaluate():
        model.eval()
        with torch.no_grad():
            logits = torch.cat([model(val_x[i:i + 256]) for i in range(0, len(val_x), 256)])
        model.train()
        return cell_metrics(logits, val_t)

    losses, history, diverged = [], [evaluate()], False
    generator = torch.Generator().manual_seed(seed)
    for _epoch in range(epochs):
        order = torch.randperm(len(train_x), generator=generator).to(train_x.device)
        for start in range(0, len(order) - batch_size + 1, batch_size):
            index = order[start:start + batch_size]
            optimizer.zero_grad()  # ① 기울기 비우기
            logits = model(train_x[index])  # ② 순전파 (B, 3, 12, 12)
            loss = loss_fn(logits, train_t[index])  # ③ 손실
            if not torch.isfinite(loss):
                diverged = True
                break
            loss.backward()  # ④ 역전파
            optimizer.step()  # ⑤ 매개변수 갱신
            losses.append(loss.item())
        if diverged:
            break
        history.append(evaluate())
    return {"losses": losses, "history": history, "model": model, "diverged": diverged}
# --8<-- [end:center_train]


CONFIGS = [
    ("(a) BCE + default bias", "(a) BCE + 기본 편향        ", "bce", None),
    ("(b) BCE + prior bias", "(b) BCE + 사전 확률 편향   ", "bce", 0.01),
    ("(c) focal + prior bias", "(c) 포컬 + 사전 확률 편향  ", "focal", 0.01),
]


def part9_imbalance(args, device, n_train: int, n_val: int, epochs: int, sgd_epochs: int, seeds: list[int]):
    print("\n[9] 불균형 실험: 도형 중심이 있는 칸 찾기")
    train_set, val_set = ShapesDataset(n_train, seed=0), ShapesDataset(n_val, seed=1)
    train_x, val_x = (train_set.images.float() / 255.0).to(device), (val_set.images.float() / 255.0).to(device)
    train_t, val_t = center_targets(train_set).to(device), center_targets(val_set).to(device)
    cells = train_t[0].numel()
    print(f"  학습 {n_train}장 · 검증 {n_val}장, 목표 모양 {tuple(train_t.shape)}, 그림당 칸 {cells}개")
    print(f"  양성 칸: 학습 {int(train_t.sum().item())}개 / {train_t.numel()}칸 = {100 * train_t.mean().item():.3f}% "
          f"(그림당 평균 {train_t.sum().item() / n_train:.2f}개)")
    n_weights = sum(p.numel() for p in CenterGridNet().parameters())
    print(f"  모델 매개변수 {n_weights:,}개, 배치 32 (에폭당 {n_train // 32} 스텝), 시드 {seeds}")

    results = {}
    for optimizer_name in ["adamw", "sgd"]:
        n_epochs = epochs if optimizer_name == "adamw" else sgd_epochs
        label = "AdamW (lr 1e-3)" if optimizer_name == "adamw" else "SGD (lr 0.01, 모멘텀 0.9)"
        print(f"  ── 옵티마이저 {label}, {n_epochs} 에폭, 시드 {len(seeds)}개 평균")
        for key, _name_ko, loss_name, prior in CONFIGS:
            results[(optimizer_name, key)] = [
                train_center(train_x, train_t, val_x, val_t, loss_name, prior, optimizer_name, n_epochs, seed)
                for seed in seeds
            ]

        def mean_of(runs, fn):
            return float(np.mean([fn(r) for r in runs]))

        def loss_at(r, step):  # 그 스텝까지 못 간 실행(발산 · 축소판)은 nan
            return r["losses"][step] if len(r["losses"]) > step else float("nan")

        print("  설정                         처음 평균 p | 손실: 1스텝째  10스텝째  100스텝째 | 1에폭 뒤: 평균 p    AP")
        for key, name_ko, _loss_name, _prior in CONFIGS:
            runs = results[(optimizer_name, key)]
            print(f"  {name_ko}  {mean_of(runs, lambda r: r['history'][0]['mean_p']):8.4f}   |"
                  f"     {mean_of(runs, lambda r: loss_at(r, 0)):8.2f}  {mean_of(runs, lambda r: loss_at(r, 9)):8.2f}"
                  f"   {mean_of(runs, lambda r: loss_at(r, 99)):8.2f}  |"
                  f"      {mean_of(runs, lambda r: r['history'][min(1, len(r['history']) - 1)]['mean_p']):8.4f}"
                  f"  {mean_of(runs, lambda r: r['history'][min(1, len(r['history']) - 1)]['ap']):.3f}")
        print(f"  마지막 에폭({n_epochs})의 검증 지표 (평균±표준편차)   평균 p     재현율         정밀도         AP          발산")
        for key, name_ko, _loss_name, _prior in CONFIGS:
            runs = results[(optimizer_name, key)]
            stats = {m: (float(np.mean([r["history"][-1][m] for r in runs])), float(np.std([r["history"][-1][m] for r in runs])))
                     for m in ["mean_p", "recall", "precision", "ap"]}
            print(f"  {name_ko}                 {stats['mean_p'][0]:.4f}   {stats['recall'][0]:.3f}±{stats['recall'][1]:.3f}"
                  f"   {stats['precision'][0]:.3f}±{stats['precision'][1]:.3f}   {stats['ap'][0]:.3f}±{stats['ap'][1]:.3f}"
                  f"   {sum(r['diverged'] for r in runs)}/{len(runs)}")
        marks = [e for e in [1, 2, 4, 8, 12, 20, 30] if e <= n_epochs]
        print("  에폭별 검증 AP                " + "".join(f"{e:>8}" for e in marks))
        for key, name_ko, _loss_name, _prior in CONFIGS:
            runs = results[(optimizer_name, key)]
            print(f"  {name_ko}  " + "".join(
                f"{mean_of(runs, lambda r, e=e: r['history'][min(e, len(r['history']) - 1)]['ap']):8.3f}" for e in marks))

    # 문턱값을 바꿔 보기: 포컬 손실로 학습한 모델의 확률은 낮게 나오는가 (AdamW, 첫 시드)
    print("  ── 문턱값에 따른 검증 재현율 · 정밀도 (AdamW, 첫 시드, 마지막 에폭)")
    for key, name_ko, _loss_name, _prior in CONFIGS:
        model = results[("adamw", key)][0]["model"]
        model.eval()
        with torch.no_grad():
            logits = model(val_x)
        pos_p = torch.sigmoid(logits)[val_t > 0.5]
        parts = []
        for threshold in [0.3, 0.5, 0.7]:
            m = cell_metrics(logits, val_t, threshold)
            parts.append(f"문턱 {threshold}: {m['recall']:.3f} · {m['precision']:.3f}")
        print(f"  {name_ko}  " + "   ".join(parts) + f"   | 양성 칸의 확률 중앙값 {pos_p.median().item():.3f}")

    # 그림 1: 과제 그림 — 그림, 정답 칸, (c) 모델의 예측
    model = results[("adamw", CONFIGS[2][0])][0]["model"]
    model.eval()
    with torch.no_grad():
        probs = torch.sigmoid(model(val_x[:4])).cpu()  # (4, 3, 12, 12)
    fig, axes = plt.subplots(2, 4, figsize=(10.0, 5.3), layout="constrained")
    cell = 96 / GRID
    markers = ["o", "s", "^"]
    for i in range(4):
        ax = axes[0, i]
        ax.imshow(val_set.images[i].permute(1, 2, 0).numpy(), interpolation="nearest")
        for g in range(1, GRID):
            ax.axhline(g * cell - 0.5, color="white", linewidth=0.3, alpha=0.5)
            ax.axvline(g * cell - 0.5, color="white", linewidth=0.3, alpha=0.5)
        for cls, row, col in val_t[i].nonzero().tolist():
            ax.add_patch(plt.Rectangle((col * cell - 0.5, row * cell - 0.5), cell, cell, fill=False, edgecolor="#39ff14", linewidth=2))
            ax.text(col * cell + cell + 1, row * cell + 1, CLASS_NAMES[cls][:3], color="#39ff14", fontsize=7, fontweight="bold")
        ax.set_title(f"image {i}: positive cells", fontsize=9)
        ax.set_xticks([])
        ax.set_yticks([])
        ax = axes[1, i]
        im = ax.imshow(probs[i].max(dim=0).values.numpy(), vmin=0, vmax=1, cmap="viridis", interpolation="nearest")
        for cls, row, col in val_t[i].cpu().nonzero().tolist():
            ax.plot(col, row, markers[cls], markerfacecolor="none", markeredgecolor="white", markersize=11, markeredgewidth=1.5)
        ax.set_title("predicted p (max over classes)", fontsize=9)
        ax.set_xticks([])
        ax.set_yticks([])
    fig.colorbar(im, ax=axes[1, :].tolist(), fraction=0.03, pad=0.02, label="probability")
    save_figure(fig, args.fig_dir, "ch04-centers.png")

    # 그림 2: 처음 스텝들의 손실, 에폭마다의 재현율 · AP
    fig, axes = plt.subplots(2, 3, figsize=(13.0, 7.0))
    for row, optimizer_name in enumerate(["adamw", "sgd"]):
        opt_label = "AdamW" if optimizer_name == "adamw" else "SGD"
        for k, (key, _name_ko, _loss_name, _prior) in enumerate(CONFIGS):
            runs = results[(optimizer_name, key)]
            n_steps = min(min(len(r["losses"]) for r in runs), 150)
            if n_steps:
                curve = np.mean([r["losses"][:n_steps] for r in runs], axis=0)
                axes[row, 0].plot(np.arange(1, n_steps + 1), curve, color=COLORS[k], linestyle=STYLES[k], linewidth=2, label=key)
            for col, metric in [(1, "recall"), (2, "ap")]:
                n_epochs = min(len(r["history"]) for r in runs)
                values = np.array([[h[metric] for h in r["history"][:n_epochs]] for r in runs])
                axes[row, col].plot(np.arange(n_epochs), values.mean(axis=0), color=COLORS[k], linestyle=STYLES[k],
                                    linewidth=2, marker="osD"[k], markersize=4, label=key)
                axes[row, col].fill_between(np.arange(n_epochs), values.min(axis=0), values.max(axis=0), color=COLORS[k], alpha=0.15)
        axes[row, 0].set_yscale("log")
        axes[row, 0].set_xscale("log")
        axes[row, 0].set_xlabel("training step")
        axes[row, 0].set_ylabel("training loss (sum / number of positives)")
        axes[row, 0].set_title(f"{opt_label}: loss in the first steps")
        axes[row, 1].set_title(f"{opt_label}: validation recall of positives (p >= 0.5)")
        axes[row, 1].set_ylabel("recall")
        axes[row, 2].set_title(f"{opt_label}: validation average precision")
        axes[row, 2].set_ylabel("AP")
        for col in [1, 2]:
            axes[row, col].set_xlabel("epoch (0 = before training)")
            axes[row, col].set_ylim(-0.03, 1.03)
        for col in range(3):
            axes[row, col].grid(alpha=0.25, which="both")
            axes[row, col].legend(fontsize=8)
    fig.tight_layout()
    save_figure(fig, args.fig_dir, "ch04-imbalance.png")


# ─────────────────────────────────────────────────────────────
# 10. 도형 분류 CNN: 학습 고리 5단계
# ─────────────────────────────────────────────────────────────

# --8<-- [start:shape_cnn]
class ShapeClassifier(nn.Module):
    """도형 하나가 그려진 그림 (B, 3, 96, 96) → 클래스 로짓 (B, 3).

    [합성곱 → 배치 정규화 → ReLU] 를 세 번(매번 가로 · 세로 절반), 전체 평균, 선형 층.
    """

    def __init__(self, num_classes: int = NUM_CLASSES, width: int = 16):
        super().__init__()
        chans = [3, width, 2 * width, 4 * width]
        blocks = []
        for c_in, c_out in zip(chans[:-1], chans[1:]):
            blocks += [nn.Conv2d(c_in, c_out, 3, stride=2, padding=1), nn.BatchNorm2d(c_out), nn.ReLU()]
        self.features = nn.Sequential(*blocks)  # (B, 3, 96, 96) → (B, 64, 12, 12)
        self.classifier = nn.Linear(chans[-1], num_classes)

    def forward(self, images: torch.Tensor) -> torch.Tensor:
        feature_map = self.features(images)  # (B, 64, 12, 12)
        pooled = feature_map.mean(dim=(2, 3))  # (B, 64): 위치 축 평균(전역 평균 풀링)
        return self.classifier(pooled)  # (B, 3) 로짓 — 소프트맥스는 손실 함수 안에서 한다
# --8<-- [end:shape_cnn]


def part10_shape_cnn(args, device, n_train: int, n_val: int, epochs: int):
    print("\n[10] 도형 분류 CNN: 학습 고리 5단계")
    train_set = ShapesDataset(n_train, seed=0, min_objects=1, max_objects=1)  # 도형 하나짜리 그림
    val_set = ShapesDataset(n_val, seed=1, min_objects=1, max_objects=1)
    train_x, val_x = (train_set.images.float() / 255.0).to(device), (val_set.images.float() / 255.0).to(device)
    train_y = torch.cat([t["labels"] for t in train_set.targets]).to(device)  # (n,) 클래스 번호
    val_y = torch.cat([t["labels"] for t in val_set.targets]).to(device)
    print(f"  학습 {tuple(train_x.shape)} · 검증 {tuple(val_x.shape)}, 클래스별 학습 그림 수 {torch.bincount(train_y, minlength=3).tolist()}")

    # --8<-- [start:train_loop]
    torch.manual_seed(args.seed)
    model = ShapeClassifier().to(device)
    optimizer = torch.optim.AdamW(model.parameters(), lr=1e-3, weight_decay=1e-4)
    batch_size = 64
    history = []
    for epoch in range(1, epochs + 1):
        model.train()  # 학습 모드: 배치 정규화가 배치 통계를 쓰고 이동 통계를 갱신한다
        order = torch.randperm(len(train_x), device=device)
        total = 0.0
        for start in range(0, len(order), batch_size):
            index = order[start:start + batch_size]
            optimizer.zero_grad()  # ① 지난 스텝의 기울기를 지운다
            logits = model(train_x[index])  # ② 순전파: (B, 3, 96, 96) → (B, 3)
            loss = F.cross_entropy(logits, train_y[index])  # ③ 손실: 소프트맥스 교차 엔트로피(배치 평균)
            loss.backward()  # ④ 역전파: 모든 매개변수의 .grad 를 채운다
            optimizer.step()  # ⑤ 갱신: θ ← θ − (AdamW 가 정한 양)
            total += loss.item() * len(index)
        model.eval()  # 추론 모드: 배치 정규화가 이동 통계를 쓴다
        with torch.no_grad():  # 평가에는 기울기가 필요 없다
            val_logits = model(val_x)
            val_loss = F.cross_entropy(val_logits, val_y).item()
            val_acc = (val_logits.argmax(dim=1) == val_y).float().mean().item()
        history.append((total / len(train_x), val_loss, val_acc))
        print(f"  에폭 {epoch:>2}: 학습 손실 {history[-1][0]:.4f}  검증 손실 {val_loss:.4f}  검증 정확도 {100 * val_acc:.1f}%")
    # --8<-- [end:train_loop]

    pred = val_logits.argmax(dim=1)
    confusion = torch.zeros(3, 3, dtype=torch.int64)
    for truth, guess in zip(val_y.tolist(), pred.tolist()):
        confusion[truth, guess] += 1
    print("  혼동 행렬 (행 = 정답, 열 = 예측; 원 · 사각형 · 삼각형)")
    for row in confusion.tolist():
        print("   ", row)
    n_params = sum(p.numel() for p in model.parameters())
    print(f"  매개변수 {n_params:,}개, 마지막 검증 정확도 {100 * history[-1][2]:.1f}% ({int((pred == val_y).sum())}/{len(val_y)})")
    # 학습 모드로 평가하면(배치 통계 사용) 결과가 달라진다는 것을 숫자로
    model.train()
    with torch.no_grad():
        acc_pairs = (torch.cat([model(val_x[i:i + 2]) for i in range(0, len(val_x), 2)]).argmax(1) == val_y).float().mean().item()
    model.eval()
    print(f"  (참고) model.train() 인 채로 2장씩 넣어 평가하면 검증 정확도 {100 * acc_pairs:.1f}%")

    fig = plt.figure(figsize=(11.0, 3.6))
    grid = fig.add_gridspec(2, 6, width_ratios=[2.4, 0.25, 1, 1, 1, 1])
    ax = fig.add_subplot(grid[:, 0])
    xs = np.arange(1, len(history) + 1)
    ax.plot(xs, [h[0] for h in history], color=COLORS[0], linewidth=2, label="train loss")
    ax.plot(xs, [h[1] for h in history], color=COLORS[1], linewidth=2, linestyle="--", label="validation loss")
    ax.set_xlabel("epoch")
    ax.set_ylabel("cross-entropy loss")
    ax.grid(alpha=0.25)
    ax2 = ax.twinx()
    ax2.plot(xs, [100 * h[2] for h in history], color=COLORS[2], linewidth=2, linestyle=":", marker="o", markersize=3, label="validation accuracy")
    ax2.set_ylabel("accuracy (%)")
    ax2.set_ylim(0, 102)
    lines = ax.get_lines() + ax2.get_lines()
    ax.legend(lines, [line.get_label() for line in lines], fontsize=8, loc="center right")
    probs = torch.softmax(val_logits[:8], dim=1).cpu()
    for i in range(8):
        axi = fig.add_subplot(grid[i // 4, 2 + i % 4])
        axi.imshow(val_set.images[i].permute(1, 2, 0).numpy(), interpolation="nearest")
        guess = int(probs[i].argmax())
        axi.set_title(f"{CLASS_NAMES[guess]} {probs[i, guess]:.2f}", fontsize=8,
                      color="black" if guess == int(val_y[i]) else "#D55E00")
        axi.set_xticks([])
        axi.set_yticks([])
    fig.tight_layout()
    save_figure(fig, args.fig_dir, "ch04-shape-cnn.png")


def main():
    parser = argparse.ArgumentParser(description="4장: 딥러닝 기초와 분류 손실")
    parser.add_argument("--quick", action="store_true", help="축소판으로 빠르게 돌려 보기")
    parser.add_argument("--fig-dir", default="figures", help="그림을 저장할 폴더")
    parser.add_argument("--seed", type=int, default=0)
    args = parser.parse_args()

    device = pick_device()
    print(f"장치: {device}" + ("  (--quick 축소판)" if args.quick else ""))
    started = time.time()
    torch.manual_seed(args.seed)
    np.random.seed(args.seed)

    part1_activations(args)
    part2_backprop(args)
    part3_adamw(args)
    part4_bce(args)
    part5_focal(args)
    part6_norm(args, n_images=128 if args.quick else 512, n_batches=50 if args.quick else 300)
    part7_residual(args)
    part8_conv(args)
    if args.quick:
        part9_imbalance(args, device, n_train=256, n_val=128, epochs=2, sgd_epochs=2, seeds=[args.seed])
        part10_shape_cnn(args, device, n_train=256, n_val=128, epochs=2)
    else:
        part9_imbalance(args, device, n_train=2000, n_val=500, epochs=30, sgd_epochs=12,
                        seeds=[args.seed, args.seed + 1, args.seed + 2])
        part10_shape_cnn(args, device, n_train=1500, n_val=500, epochs=8)
    print(f"\n끝. 걸린 시간 {time.time() - started:.1f}초")


if __name__ == "__main__":
    main()
