Update docs: symbol tables, terminated/truncated, run commands

q_learning/q-learning.md

@@ -1,7 +1,5 @@
 # Q-Learning 走迷宫：简明原理与推导
 
-> 对应代码 `q_learning.py`（numpy 实现，可选 matplotlib 绘图）。本文不含代码，只保留核心公式与结论。行内公式用 `$...$`、独立公式用 `$$...$$`，Gitea 网页端可直接渲染；建议搭配支持数学渲染的本地查看器（VSCode 预览、Typora、Obsidian）使用。
-
 ---
 
 ## 一、问题：迷宫 = 马尔可夫决策过程（MDP）
@@ -28,6 +26,20 @@ $$G_t=\sum_{k=0}^{\infty}\gamma^{k}R_{t+k+1}$$
 
 其绝对值的上界为 $|G_t|\le 100/(1-\gamma)$，即收敛有界。目标是最大化起点期望回报：$\pi^{*}=\arg\max_{\pi}\mathbb{E}_{\pi}[G_0]$。
 
+**符号说明**（全文记号约定）：
+
+| 符号 | 含义 |
+|---|---|
+| $t$ | 离散时间步编号（第几步）；一条轨迹为 $\cdots\to S_t\to A_t\to R_{t+1}\to S_{t+1}\to A_{t+1}\to R_{t+2}\to\cdots$ |
+| $S_t,\ A_t,\ R_{t+1}$ | 第 $t$ 步所处的状态、执行的动作、以及该步之后拿到的即时奖励 |
+| 奖励下标 $t{+}1$ | 约定：$R_{t+1}$ 是执行 $A_t$、转移到 $S_{t+1}$ 时得到的奖励，写在引发它的动作之后 |
+| 大写 vs 小写 | 大写（$S_t,A_t,R_{t+1},G_t$）= 随机变量（结局未定）；小写（$s,a,r$）= 具体取值（已发生的实际值） |
+| $s'$ | 走一步之后到达的新状态，即 $S_{t+1}=s'$ |
+| $\gamma$ | 折扣因子，$\gamma^{k}$ 给 $k$ 步之后的奖励加权，本例取 0.9 |
+| $G_t$ | 回报：从 $t$ 时刻起未来全部奖励的折扣和，"从这里玩到底的打折总分" |
+| $\mathbb{E}[\,\cdot\mid\cdot\,]$ | 条件期望："在竖线右边的前提下，左边量的长期平均" |
+| $\pi$ | 策略：每个状态下选各动作的概率规则；$\pi(a\mid s)$ 表示在 $s$ 选 $a$ 的概率 |
+
 ---
 
 ## 二、价值函数与贝尔曼方程
@@ -70,6 +82,17 @@ $$Q(s,a)\leftarrow Q(s,a)+\alpha[r+\gamma\max_{a'}Q(s',a')-Q(s,a)]$$
 
 其中 $\alpha=0.1$，$\delta_t=r+\gamma\max_{a'}Q(s',a')-Q(s,a)$。
 
+**符号说明**：
+
+| 符号 | 含义 |
+|---|---|
+| $\leftarrow$ | 赋值：把右端算出的数写进 Q 表的 $(s,a)$ 位置，不是数学等式 |
+| $\alpha$ | 学习率（0~1 之间）：本次按多大比例采纳误差 |
+| $\delta_t$ | TD 误差：新信息与旧预期之差。$\delta_t>0$ 说明实际比预期好，上调；反之下调 |
+| $Y=r+\gamma\max_{a'}Q(s',a')$ | TD 目标：一步真实奖励 $r$ + 下一状态最优价值的现有估计（"标签"） |
+| $\max_{a'}$ | 对 $s'$ 处全部 4 个动作的 Q 值取最大，即"假设下一步走最优"——off-policy 的来源 |
+| $s',\ a'$ | 到达的新状态、以及在其处设想尝试的动作（只用来查表估值，并不真的执行） |
+
 关键结论：
 
 - **收敛**：需每个 $(s,a)$ 被访问无穷多次，且学习率满足 $\sum\alpha=\infty$、$\sum\alpha^{2}<\infty$（Watkins 1992，以概率 1 收敛）。本实现取常数 $\alpha$，确定性环境下无采样噪声，固定 $(s,a)$ 可解析解：
@@ -79,7 +102,8 @@ $$Q(s,a)\leftarrow Q(s,a)+\alpha[r+\gamma\max_{a'}Q(s',a')-Q(s,a)]$$
   误差以 $(1-\alpha)^{k}$ 几何衰减（$\alpha=0.1$ 时约 22 次访问缩小一个数量级）；真正的瓶颈是价值逐层传播（层数 = 最短路长 $D$），故迷宫越大越需更多训练。
 - **Off-policy**：未来项用 $\max_{a'}Q(s',\cdot)$，与行为策略（含探索）无关，因此收敛到 $Q^{*}$。
 - **vs SARSA**：SARSA 的未来项用实际执行的 $a'$，逼近 $\mathbb{E}_{a'\sim\pi_\varepsilon}[\cdot]$ 而非 max，收敛到 ε-greedy 策略自身的价值；在带陷阱环境里 SARSA 学出保守绕行，Q-Learning 学理论最优。
-- **终止状态**：$done$ 时目标值不含 bootstrap 项，仅为 $r$。
+- **vs Monte Carlo**：MC 等一局结束，用真实回报 $G_t$ 作目标——无偏，但含整局探索噪声（方差大），且必须等回合结束、只有到达过终点的局才有强信号；TD 单步自举——有偏（初期 $Q$ 尚未传开导致系统性低估，$\max$ 算子带来高估），但方差小、每步可学、样本利用率高。实践中 TD 几乎总收敛更快。
+- **终止与截断**：`terminated`（到达终点，真正的终止状态）时目标值不含 bootstrap 项，仅为 $r$；超时截断 `truncated`（达到 `max_steps`）**不是**终止状态，目标仍含 bootstrap 项——回合只是被强制叫停，未来价值依然存在。
 
 ---
 
@@ -144,7 +168,7 @@ $$V(d)=\gamma^{d-1}(100+\frac{1}{1-\gamma})-\frac{1}{1-\gamma}$$
 
 ## 七、运行与观察
 
-运行参数：`--rows/--cols`（默认 9，须为奇数）、`--seed`、`--episodes`（默认 500）、`--braid`（默认 0）、`--plot`。输出：迷宫、策略箭头、贪心路径、成功率统计；加 `--plot` 生成两张图。
+在仓库根目录运行：`python -m q_learning.q_learning --plot`；参数：`--rows/--cols`（默认 9，须为奇数）、`--seed`、`--episodes`（默认 500）、`--braid`（默认 0）、`--plot`。环境接口遵循 Gymnasium 风格：`reset()` 返回 `(obs, info)`，`step(a)` 返回 `(obs, r, terminated, truncated, info)`。输出：迷宫、策略箭头、贪心路径、成功率统计；加 `--plot` 生成两张图。
 
 | 图 | 数学对象 | 判读 |
 |---|---|---|