---
tags: [nanochat, math, muon]
阶段: 02-数学与工程基础
难度: ★★★
created: 2026-10-22
related: "[[梯度下降与AdamW]], [[矩阵与线性代数速查]], [[FLOPs与训练成本估算]]"
---

# Muon优化器

## 定义

**Muon**（MomentUm Orthogonalized by Newton-Schulz）是一类用于二维矩阵参数的优化器：先对动量累积后的梯度做正交化，再用正交化结果更新参数。nanochat 的实现（`nanochat/optim.py` 的 `muon_step_fused`）可以写成

$$
\mathbf{G}_{t}=\text{正交化}\Big(\mathbf{G}^{\text{nes}}_{t}\Big),\qquad
\mathbf{W}_{t+1}=\mathbf{W}_{t}-\eta\,\mathbf{G}_{t}-\eta\lambda\,\mathbf{W}_{t}\odot\mathbf{1}\big[\mathbf{G}_{t}\odot\mathbf{W}_{t}\ge0\big],
$$

其中 $\odot$ 为逐元素乘，$\mathbf{1}[\cdot]$ 为示性函数。正交化由三步组成：行均衡（MuonEq）、Polar Express 迭代、范数重整（Muon+）。

符号与术语：

- $\mathbf{G}_t\in\mathbb{R}^{m\times n}$：第 $t$ 步最终的更新矩阵，即动量、正交化与 NorMuon 缩放全部完成之后的结果；$\mathbf{G}^{\text{nes}}_t$ 是 Nesterov 动量组合后的梯度，尚未正交化。
- **正交化**：把 $\mathbf{G}$ 换成离它最近的列正交（或行正交）矩阵 $\mathbf{Q}=\mathbf{U}\mathbf{V}^{\top}$，$\mathbf{G}=\mathbf{U}\mathbf{\Sigma}\mathbf{V}^{\top}$ 为 SVD。
- **Polar Express**：用五次多项式迭代逼近 $\mathbf{U}\mathbf{V}^{\top}$ 的方法，避免显式 SVD。
- **Newton–Schulz 迭代**：只含矩阵乘法的迭代，形式为 $\mathbf{X}\leftarrow a\mathbf{X}+b\mathbf{X}(\mathbf{X}^{\top}\mathbf{X})+c\mathbf{X}(\mathbf{X}^{\top}\mathbf{X})^{2}$。
- **MuonEq**：按行把 $\mathbf{G}$ 的每一行缩放到平均行范数，改善进入迭代的谱条件。
- **Muon+**：把正交化结果的 Frobenius 范数拉回 $\sqrt{\min(m,n)}$。
- **NorMuon**：在正交化之后按行（或列）做方差归一化，等价于逐神经元的自适应学习率。
- **cautious weight decay**：仅当更新与参数同号时才施加的权重衰减。
- $\mu$：动量系数；$\beta_2$：NorMuon 二阶矩的衰减率；$\lambda$：权重衰减系数；$N$：数据并行进程数。

## 为什么重要

- d24 的 156 个矩阵张量共 679,478,976 个参数，占全部矩阵参数（729,810,648）的 93.1%、全部参数（1,384,122,122）的 49.1%。这些参数全部走 Muon，其余走 AdamW。不看懂 Muon，等于不看懂这份代码库一半的优化器。
- 逐元素优化器（SGD、AdamW）没有「矩阵」这个概念：它们把每个坐标独立处理。矩阵参数的有效更新受奇异值谱支配，谱很扁时少数方向吃掉大部分步长。Muon 的做法是把谱压平，使每个方向获得相同的步幅。这是它与 AdamW 的根本差别，也是它能在相同 token 预算下更快的原因（见 Muon 论文与 modded-nanogpt 的报告）。
- nanochat 的 Muon 不是原始版本：它融合了 Polar Express（2505.16932）、NorMuon（2510.05491）与 cautious weight decay（2411.16085），另外还有仓库注释引用的两处轻微改进。这些组件在代码里交织在一个融合核中，必须逐段拆开才能核对。
- 分布式训练下 Muon 有独立的通信模式：参数栈跨 rank 切分、`reduce_scatter` 取梯度分片、`all_gather` 回填参数。05 阶段的优化器分片讨论以本篇为前置。
- 在全书中的位置：前置是 [[矩阵与线性代数速查]] 的 SVD 与极分解、[[梯度下降与AdamW]] 的参数分组与调度；后续是 05 阶段的分布式训练。通用优化理论见 [[优化算法-梯度下降与Adam]]（跨库），本篇只讲 Muon 的机制与 nanochat 的实现。

## 原理与推导

### 1. 为什么矩阵更新需要正交化

设当前参数为 $\mathbf{W}$，损失在 $\mathbf{W}$ 处的梯度为 $\mathbf{G}$。一阶近似下，参数位移 $\Delta$ 带来的损失变化是

$$
\mathcal{L}(\mathbf{W}-\Delta)\approx\mathcal{L}(\mathbf{W})-\langle\mathbf{G},\Delta\rangle ,
$$

因此「在给定预算内让损失下降最多」等价于在某个范数约束下最大化 $\langle\mathbf{G},\Delta\rangle$。不同范数约束给出完全不同形状的 $\Delta$：

- 若约束 Frobenius 范数 $\|\Delta\|_F\le\epsilon$，由 Cauchy–Schwarz，$\langle\mathbf{G},\Delta\rangle$ 在 $\Delta=\epsilon\,\mathbf{G}/\|\mathbf{G}\|_F$ 取最大，即**未作逐元素缩放的梯度**，也就是最速下降。
- 若约束逐坐标上界 $|\Delta_{ij}|\le\epsilon$，最优解是 $\Delta=\epsilon\,\mathrm{sign}(\mathbf{G})$。Adam 在 $\varepsilon\ll|\mathbf{g}|$ 时的步长 $\eta\,\hat{\mathbf{m}}/\sqrt{\hat{\mathbf{v}}}\approx\eta\,\mathrm{sign}(\mathbf{g})$ 属于这一类：逐坐标归一化等价于给每个坐标单独一个盒约束。
- 若约束谱范数 $\|\Delta\|_2\le\epsilon$（最大拉伸倍数不超过 $\epsilon$），则最优解是

$$
\Delta^{\star}=\epsilon\,\mathbf{U}\mathbf{V}^{\top},
$$

即 $\mathbf{G}$ 的正交因子。证明：$\|\Delta\|_F\le\sqrt{r}\|\Delta\|_2\le\sqrt r\,\epsilon$，其中 $r$ 为秩；而 $\|\epsilon\mathbf{U}\mathbf{V}^{\top}\|_F=\epsilon\sqrt r$ 取到上界，且 $\langle\mathbf{G},\epsilon\mathbf{U}\mathbf{V}^{\top}\rangle=\epsilon\sum_i\sigma_i=\epsilon\|\mathbf{G}\|_*$ 是所有 $\|\Delta\|_2\le\epsilon$ 的矩阵中最大的（von Neumann 迹不等式）。

三种预算的差别在于「预算花在哪里」。Frobenius 预算允许把全部位移堆在一个奇异方向上；盒约束只限制单个坐标；谱预算限制单方向的最大拉伸，因此最优解被迫把 $\epsilon$ 均匀分给所有方向。Muon 选择第三种，理由是实验发现这样训练的模型更好，而不是因为谱预算在理论上更优。

第二条动机来自「最近正交矩阵」这一变分刻画：$\mathbf{U}\mathbf{V}^{\top}$ 是 $\mathbf{G}$ 在正交群上的 Frobenius 投影（证明见 [[矩阵与线性代数速查]] 第 5 节）。因此正交化保留了更新矩阵的方向结构（$\mathbf{U},\mathbf{V}$），只把强度结构调整为全 1。用一句话概括：**Muon 认为更新矩阵的奇异值不重要，方向重要。**

还有一条实用的性质：正交化把更新的谱范数压到 1 附近、把 Frobenius 范数压到 $\sqrt{\min(m,n)}$ 附近，于是不同形状、不同尺度的矩阵更新被放到同一量级上，一个全局学习率对所有矩阵组都适用。这与 AdamW 的逐元素归一化目标相同，但归一化的对象从「坐标」变成了「奇异方向」。

### 2. 动量与 Nesterov 组合

nanochat 先做标准动量，再取 Nesterov 形式的线性组合：

$$
\mathbf{M}_t=\mathbf{M}_{t-1}+(1-\mu)\big(\mathbf{G}^{\text{raw}}_t-\mathbf{M}_{t-1}\big),\qquad
\mathbf{G}^{\text{nes}}_t=\mathbf{G}^{\text{raw}}_t+\mu\big(\mathbf{M}_t-\mathbf{G}^{\text{raw}}_t\big).
$$

首步 $\mathbf{M}_0=\mathbf{0}$ 时 $\mathbf{M}_1=(1-\mu)\mathbf{G}^{\text{raw}}$，于是 $\mathbf{G}^{\text{nes}}_1=(1-\mu^{2})\mathbf{G}^{\text{raw}}$。以 $\mu=0.95$ 计，比例系数是 $0.0975$。这个整体缩放看起来会改变步长，但正交化第一步就按 Frobenius 范数归一化，把系数完全消掉。因此在这里 Nesterov 只影响方向组合，不影响步长。

动量系数本身是调度的：`get_muon_momentum` 在前 400 步从 0.85 线性升到 0.97，在 warmdown 段从 0.97 线性降到 0.90。训练末段降低动量，等效于减少历史平均长度，让参数更快跟上当前梯度。

### 3. Polar Express 迭代

原始 Muon 用 Newton–Schulz 迭代计算 $\mathbf{U}\mathbf{V}^{\top}$。nanochat 改用 Polar Express（2505.16932）的五次多项式迭代，每一轮使用一组不同的系数（下式以高矩阵 $m>n$ 为例，宽矩阵用转置形式，见本节末）：

$$
\mathbf{X}_{k+1}=a_k\mathbf{X}_k+b_k\,\mathbf{X}_k\big(\mathbf{X}_k^{\top}\mathbf{X}_k\big)+c_k\,\mathbf{X}_k\big(\mathbf{X}_k^{\top}\mathbf{X}_k\big)^{2},\qquad k=1,\dots,5 .
$$

五组系数（与 `polar_express_coeffs` 逐位一致）：

| 迭代 | $a_k$ | $b_k$ | $c_k$ |
|---|---|---|---|
| 1 | 8.156554524902461 | −22.48329292557795 | 15.878769915207462 |
| 2 | 4.042929935166739 | −2.808917465908714 | 0.5000178451051316 |
| 3 | 3.8916678022926607 | −2.772484153217685 | 0.5060648178503393 |
| 4 | 3.285753657755655 | −2.3681294933425376 | 0.46449024233003106 |
| 5 | 2.3465413258596377 | −1.7097828382687081 | 0.42323551169305323 |

三处实现细节。

**预归一化。** 迭代前先做

$$
\mathbf{X}_0=\frac{\mathbf{X}}{\|\mathbf{X}\|_F\cdot1.01+10^{-6}} .
$$

分母乘 $1.01$ 是安全因子：它保证 $\sigma_{\max}(\mathbf{X}_0)<1/1.01$，使五次多项式在迭代初期不因谱半径过大而发散。$10^{-6}$ 防止零矩阵除零。

**高/宽矩阵分支。** 当 $m>n$ 时代码计算 $\mathbf{A}=\mathbf{X}^{\top}\mathbf{X}\in\mathbb{R}^{n\times n}$ 并右乘；否则计算 $\mathbf{A}=\mathbf{X}\mathbf{X}^{\top}\in\mathbb{R}^{m\times m}$ 并左乘。两者是同一迭代在转置下的两种写法，见 [[矩阵与线性代数速查]] 第 3 节。选择较小的一侧构造 $\mathbf{A}$，可以把每次迭代的矩阵乘法开销从 $O(m^{2}n)$ 降到 $O(mn\cdot\min(m,n))$。

**不收敛到精确极分解。** 仓库注释明确写了：系数按「零点斜率最大」选取，迭代并不收敛到 $\mathbf{U}\mathbf{V}^{\top}$，而是得到 $\mathbf{U}\mathbf{S}'\mathbf{V}^{\top}$，其中 $\mathbf{S}'$ 的对角元大致落在 $(0.5,1.5)$。本篇的例子会看到 $\sigma$ 在迭代中先冲高到约 1.93 再回落到 0.92，最终两个奇异值是 1.033 与 0.966，而不是精确的 1。这也解释了为什么需要后面的 Muon+ 范数重整。

### 4. NorMuon 方差缩放

正交化之后，$\mathbf{G}$ 的各行（或各列）范数并不相同：$\mathbf{S}'$ 不完全等于 $\mathbf{I}$，且 $\mathbf{U}$ 的行范数也不相等。NorMuon（2510.05491）在正交化之后再加一层逐神经元的自适应缩放。nanochat 的实现是：

$$
\mathbf{v}_t=\beta_2\mathbf{v}_{t-1}+(1-\beta_2)\,\overline{\mathbf{G}_t^{2}},\qquad
\mathbf{s}_t=\big(\max(\mathbf{v}_t,10^{-10})\big)^{-1/2},
$$

其中 $\overline{\mathbf{G}^{2}}$ 表示沿「被归约维」取均值：高矩阵（$m\ge n$）沿列取均值得到 $(m,1)$，宽矩阵沿行取均值得到 $(1,n)$。$\mathbf{s}_t$ 的广播形状与之一致。

随后做一次保范数修正。设 $r$ 为被归约维的长度，代码计算

$$
\|\mathbf{G}\|_F^{2}=\Big(\sum_{\text{全部元素}}\overline{\mathbf{G}^{2}}\Big)\cdot r,\qquad
\|\mathbf{G}'\|_F^{2}=\sum_{\text{全部元素}}\big(\overline{\mathbf{G}^{2}}\cdot r\cdot\mathbf{s}_t^{2}\big),
$$

$$
\mathbf{G}'_t=\mathbf{G}_t\odot\Big(\mathbf{s}_t\cdot\frac{\|\mathbf{G}_t\|_F}{\|\mathbf{G}'_t\|_F}\Big).
$$

第二个等式把缩放后的范数算出来，第三个等式把它拉回原值，于是**正交化给出的 $\|\mathbf{G}\|_F=\sqrt{\min(m,n)}$ 在缩放后仍然成立**。这一步是关键：没有它，逐行归一化会改变更新总幅值，学习率就失去意义。

注意代码里 $\mathbf{v}_t$ 没有偏差修正。首步 $\mathbf{v}_1=0.1\,\overline{\mathbf{G}^{2}}$，$\mathbf{s}_1$ 因此比稳态大约 $\sqrt{10}$ 倍；但保范数修正随即把整体幅度拉回，所以前几步不会出现步长爆炸。这是与 Adam 的一个明确差异。

### 5. MuonEq 行均衡与 Muon+ 范数重整

**MuonEq** 在进入 Polar Express 之前把每行的范数缩放到平均值：

$$
\bar\rho=\frac{\|\mathbf{X}\|_F}{\sqrt m},\qquad
\mathbf{X}\leftarrow\mathbf{X}\cdot\mathrm{diag}\Big(\frac{\bar\rho}{\|\mathbf{x}_i\|_2}\Big).
$$

动机是条件数：若各行范数差异很大，$\mathbf{X}^{\top}\mathbf{X}$ 的对角元差异随之变大，谱更扁，五次多项式在有限步内更难把谱压平。行均衡把对角元拉到同一量级，改善迭代的收敛条件。仓库注释把该改进归于一篇 arXiv 编号 2603.28254 的工作；该文献不在本库参考池内，本篇只按代码行为描述，不转述其论证。

**Muon+** 在迭代之后把范数拉回：

$$
\mathbf{X}\leftarrow\mathbf{X}\cdot\frac{\sqrt{\min(m,n)}}{\|\mathbf{X}\|_F}.
$$

它修正的是迭代未完全收敛导致的范数偏差。第 1 节已经说明 $\sqrt{\min(m,n)}$ 是「谱范数为 1 的矩阵所能达到的最大 Frobenius 范数」，因此这一步等价于把更新放回谱预算的边界上。仓库注释把该改进归于 arXiv 编号 2602.21545，同样不在参考池内。

### 6. cautious weight decay

标准权重衰减无视梯度方向，总是把参数往零拉。**cautious weight decay**（2411.16085）只在更新与参数同号时衰减：

$$
\mathbf{W}\leftarrow\mathbf{W}-\eta\mathbf{G}-\eta\lambda\,\mathbf{W}\odot\mathbf{1}\big[\mathbf{G}\odot\mathbf{W}\ge0\big].
$$

理由可以直接验证。若 $G_{ij}W_{ij}>0$：当 $W_{ij}>0$ 时 $G_{ij}>0$，更新项 $-\eta G_{ij}$ 使 $|W_{ij}|$ 减小；当 $W_{ij}<0$ 时 $G_{ij}<0$，$-\eta G_{ij}>0$ 同样使 $|W_{ij}|$ 减小。也就是说，同号时更新本身已经在收缩参数，叠加衰减方向一致。若异号，更新在增大 $|W_{ij}|$，此时衰减会与梯度对抗，跳过它可以让模型保留必要的权重增长。

nanochat 的权重衰减还带调度：$\lambda_t=\lambda_{\text{scaled}}\cdot\frac{1+\cos(\pi t/N)}{2}$，从最大值余弦降到 0。$\lambda_{\text{scaled}}$ 由 `base_train.py` 的 T_epoch 公式给出，推导见 [[梯度下降与AdamW]] 第 5 节。

### 在 nanochat 中的落地

**融合核逐段。** `muon_step_fused` 的签名是

```text
stacked_grads: (K, m, n), stacked_params: (K, m, n), momentum_buffer: (K, m, n),
second_momentum_buffer: (K, m, 1) 或 (K, 1, n),
momentum_t / lr_t / wd_t / beta2_t: 0-D CPU 张量, ns_steps: 5, red_dim: -1 或 -2
```

按执行顺序拆成七段，与前面各节对应：

| 段 | 代码行为 | 对应公式 |
|---|---|---|
| 1 动量 | `momentum_buffer.lerp_(grads, 1-μ)`，`g = grads.lerp_(buf, μ)` | 第 2 节的 $\mathbf{M}_t$ 与 $\mathbf{G}^{\text{nes}}_t$ |
| 2 转 bf16 | `X = g.bfloat16()`（仅当 `COMPUTE_DTYPE` 是 bf16） | 迭代在 bf16 下稳定，节省寄存器与带宽 |
| 3 MuonEq | `target = ‖X‖_F/√m`，`X *= target/row_norm` | 第 5 节 |
| 4 预归一化 | `X = X/(‖X‖_F*1.01 + 1e-6)` | 第 3 节 |
| 5 Polar Express | 5 轮，高矩阵用 $\mathbf{X}^{\top}\mathbf{X}$，宽矩阵用 $\mathbf{X}\mathbf{X}^{\top}$ | 第 3 节 |
| 6 Muon+ | `target_norm = √min(m,n)`，按比例缩放 | 第 5 节 |
| 7 NorMuon + 更新 | `v_mean` 均值、`second_momentum_buffer.lerp_`、`final_scale`、cautious 掩码、`params.sub_` | 第 4、6 节 |

第 2 段有一个限制：只有当 `COMPUTE_DTYPE == torch.bfloat16` 时才转 bf16。fp16 的指数范围只有 5 位，五次多项式迭代的中间值会溢出，因此 fp16 路径直接沿用输入精度。第 7 段最后一行把更新与衰减合成一次 `sub_`：

```text
mask = (g * stacked_params) >= 0
stacked_params.sub_(lr * g + lr * wd * stacked_params * mask)
```

**参数分组与形状倍数。** `setup_optimizer` 中 `matrix_params = list(self.transformer.h.parameters())`，即每个 block 的 `c_q`、`c_k`、`c_v`、`c_proj`、`mlp.c_fc`、`mlp.c_proj` 与 `ve_gate`。按形状分组后：

| 形状 | 张量数 | 栈形状 | 学习率倍数 |
|---|---|---|---|
| $(12,12)$ | 12 | $(12,12,12)$ | 1（`ve_gate`） |
| $(1536,1536)$ | 96 | $(96,1536,1536)$ | 1 |
| $(6144,1536)$ | 24 | $(24,6144,1536)$ | 2（`c_fc`，高矩阵） |
| $(1536,6144)$ | 24 | $(24,1536,6144)$ | 1（`mlp.c_proj`，宽矩阵） |

学习率倍数来自 `_compute_muon` 的一行：

```text
self._muon_lr_t.fill_(group["lr"] * max(1.0, shape[-2] / shape[-1])**0.5)
```

即 $\eta_{\text{eff}}=\eta\cdot\sqrt{\max(1,m/n)}$。d24 的 `group["lr"]` 为 $0.02\times\sqrt2=0.028284$，因此 `mlp.c_fc` 的有效学习率是 $0.056569$，其余矩阵组是 $0.028284$。注意这个倍数只放大高矩阵，宽矩阵不变；`dev/LOG.md` 2026-02-03 记录过一次「翻转该启发式、改为放大宽矩阵」的实验（PR #492），当前 master 仍保留原写法。

**哪些参数不进 Muon。** `wte`、`lm_head`、`value_embeds`、`resid_lambdas`、`x0_lambdas`、`smear_gate` 与两个标量走 AdamW。原因之一是 Muon 的最初警告：嵌入层与最终全连接层不应使用 Muon；原因之二是这些张量要么是查表（`wte`、`value_embeds`），要么是 1 维标量，没有可正交化的二维谱结构。`ve_gate` 虽然是 $(n_{\text{kv}},12)$ 的小矩阵，但它位于 `transformer.h` 内，按代码的分组规则仍归 Muon。

**单卡与分布式。** 同一个 `MuonAdamW` 类覆盖两种情形，差别只在通信：

| 项目 | 单卡 | 多卡（ZeRO-2 式分片） |
|---|---|---|
| 梯度同步 | 无（梯度就是本地梯度） | 优化器内部 `reduce_scatter` / `all_reduce`，不使用 DDP |
| Muon 梯度栈 | `torch.stack` 后即「本 rank 的全部分片」 | 补齐到 $\lceil K/N\rceil\cdot N$ 后 `reduce_scatter`，每 rank 得 $\lceil K/N\rceil$ 个张量的梯度 |
| Muon 参数更新 | 全部本地更新 | 只更新自己分片，再 `all_gather` 回填 |
| 优化器状态 | 全量保存在本 rank | `momentum_buffer` 与 `second_momentum_buffer` 按分片保存 |
| 缓冲区复用 | 不需要 | `stacked_grads` 复用为 `all_gather` 的输出 |
| 参数回填 | 直接映射 | `torch._foreach_copy_` 从栈写回各参数 |

分片数量 $K$ 不整除 $N$ 时补零：`updated_params[num_owned:].zero_()`，回填时按 `len(params)` 截断，零行不会写进参数。AdamW 组的分片规则不同：元素数小于 1024 的参数（标量、门控）走 `all_reduce` 并全量更新状态；大参数沿第 0 维 `reduce_scatter`，要求 `shape[0] % world_size == 0`。d24 的 `wte`、`lm_head`、`value_embeds` 第 0 维都是 32768，8 卡时每卡 4096 行。

**精度。** 参数状态用 `torch.zeros_like(p_slice)` 或 `torch.zeros(chunk_size, *shape, dtype=dtype)` 分配，dtype 跟随参数。`init_weights` 只把 `wte` 与 `value_embeds` 转到 `COMPUTE_DTYPE`（bf16），`lm_head` 与 transformer 块的矩阵仍是 fp32，因此：`wte`、`value_embeds` 的 AdamW 状态是 bf16，Muon 矩阵的参数与动量/二阶矩都是 fp32，`lm_head` 的 AdamW 状态是 fp32。这与 AdamW 核的处理一致：状态跟随参数精度，算术过程统一转 fp32。

> [!info] 版本说明
> `dev/LOG.md` 2026-01-10 条目写 NorMuon 的 `beta2=0.95`、权重衰减「线性 schedule 到 0」、默认 `--weight-decay` 为 0.2；当前代码分别是 `beta2=0.9`（`setup_optimizer`）、余弦调度 $\frac{1+\cos(\pi t/N)}{2}$（`get_weight_decay`）、默认 0.28（`base_train.py`）。同一条目还说 Polar Express「no dramatic/noticeable difference」，MuonEq 与 Muon+ 则引用了参考池之外的 arXiv 编号。以代码为准。

## 关键直觉

> [!tip] 正交化是「把更新的谱预算花满」
> 若只约束更新的谱范数（最大拉伸）为 $\epsilon$，则在所有方向等量分配的 $\epsilon\mathbf{U}\mathbf{V}^{\top}$ 能让 Frobenius 位移达到最大 $\epsilon\sqrt{\min(m,n)}$。Muon 因此可以读作：给定最大拉伸预算，把所有奇异方向都用满。与 Adam 的对照最能说明问题：Adam 让每个**坐标**的位移相同，Muon 让每个**奇异方向**的位移相同。与严格定义的关系：$\epsilon\mathbf{U}\mathbf{V}^{\top}$ 的最优性由 von Neumann 迹不等式保证，是定理而不是经验；「这样训练更好」才是经验结论。

## 例子与代码

### 例 1：$2\times3$ 矩阵的正交化全流程

```python
import numpy as np

COEFFS = [
    (8.156554524902461, -22.48329292557795, 15.878769915207462),
    (4.042929935166739, -2.808917465908714, 0.5000178451051316),
    (3.8916678022926607, -2.772484153217685, 0.5060648178503393),
    (3.285753657755655, -2.3681294933425376, 0.46449024233003106),
    (2.3465413258596377, -1.7097828382687081, 0.42323551169305323),
]

def orthogonalize(G, steps=5):
    m, n = G.shape
    # MuonEq：把每一行的范数缩放到均值 ||G||_F/sqrt(m)
    target = np.linalg.norm(G) / np.sqrt(m)
    X = G * (target / np.linalg.norm(G, axis=1, keepdims=True))
    # 整体缩放：保证进入迭代的谱半径 <= 1/1.01
    X = X / (np.linalg.norm(X) * 1.01 + 1e-6)
    for k, (a, b, c) in enumerate(COEFFS[:steps], 1):
        if m > n:                                  # 高矩阵
            A = X.T @ X
            X = a * X + X @ (b * A + c * (A @ A))
        else:                                      # 宽矩阵，本例走这一支
            A = X @ X.T
            X = a * X + (b * A + c * (A @ A)) @ X
        print(f"iter {k}: sigma={np.round(np.linalg.svd(X, compute_uv=False), 6)} "
              f"||X||_F={np.linalg.norm(X):.6f}")
    # Muon+：把 Frobenius 范数拉回 sqrt(min(m, n))
    return X * (np.sqrt(min(m, n)) / np.linalg.norm(X))

G = np.array([[1.0, 2.0, 3.0], [0.5, 1.0, 2.5]])
U, S, Vt = np.linalg.svd(G, full_matrices=False)
print("sigma(G) =", S)
Q = orthogonalize(G)
print("sigma(Q) =", np.round(np.linalg.svd(Q, compute_uv=False), 6))
print("||Q||_F =", round(float(np.linalg.norm(Q)), 6))
print("Q @ Q.T =\n", np.round(Q @ Q.T, 6))
print("||Q @ Q.T - I||_F =", round(float(np.linalg.norm(Q @ Q.T - np.eye(2))), 6))
```

预期输出：

```text
sigma(G) = [4.61138487 0.48490162]
iter 1: sigma=[1.255248 0.857874] ||X||_F=1.520393
iter 2: sigma=[1.927242 1.07756 ] ||X||_F=2.208030
iter 3: sigma=[1.459806 1.109075] ||X||_F=1.833326
iter 4: sigma=[1.192947 0.508861] ||X||_F=1.296943
iter 5: sigma=[0.983216 0.919142] ||X||_F=1.345933
sigma(Q) = [1.033095 0.965771]
||Q||_F = 1.414214
Q @ Q.T =
 [[1.       0.067285]
 [0.067285 1.      ]]
||Q @ Q.T - I||_F = 0.095156
```

原始矩阵的条件数是 $4.611/0.485=9.51$；迭代后两个奇异值为 1.033 与 0.966，条件数 1.07。中间第 2 轮谱冲到 1.93 是五次多项式的过冲，第 5 轮才回落——这正是「5 组系数、不追求完全收敛」的含义。最后 $\mathbf{Q}\mathbf{Q}^{\top}$ 与单位阵的偏差是 0.095，说明行只是近似正交；Muon+ 把 $\|\mathbf{Q}\|_F$ 精确拉回 $\sqrt2=1.414214$。

### 例 2：单步完整更新（动量 → 正交化 → NorMuon → cautious WD）

```python
import numpy as np

COEFFS = [
    (8.156554524902461, -22.48329292557795, 15.878769915207462),
    (4.042929935166739, -2.808917465908714, 0.5000178451051316),
    (3.8916678022926607, -2.772484153217685, 0.5060648178503393),
    (3.285753657755655, -2.3681294933425376, 0.46449024233003106),
    (2.3465413258596377, -1.7097828382687081, 0.42323551169305323),
]
def polar(G, steps=5):
    m, n = G.shape
    X = G * ((np.linalg.norm(G) / np.sqrt(m)) / np.linalg.norm(G, axis=1, keepdims=True))
    X = X / (np.linalg.norm(X) * 1.01 + 1e-6)
    for a, b, c in COEFFS[:steps]:
        A = X @ X.T if m <= n else X.T @ X
        X = a * X + ((b * A + c * (A @ A)) @ X if m <= n else X @ (b * A + c * (A @ A)))
    return X * (np.sqrt(min(m, n)) / np.linalg.norm(X))

G = np.array([[1.0, 2.0, 3.0], [0.5, 1.0, 2.5]])
P = np.array([[0.01, 0.02, 0.03], [0.005, 0.01, 0.025]])
mu, lr, wd, beta2 = 0.95, 0.02, 0.1, 0.9

buf = np.zeros_like(G)                       # 首步：动量缓冲为零
buf = buf + (1 - mu) * (G - buf)
g = G + mu * (buf - G)
print("nesterov g =", np.round(g, 6))        # 0.0975 * G
g = polar(g)

red = g.shape[0]                             # 宽矩阵：按行取均值，red_dim=-2
v_mean = np.mean(g.astype(np.float64) ** 2, axis=0, keepdims=True)
v_norm = np.sqrt(float(v_mean.sum()) * red)
buf2 = 0.1 * v_mean                          # beta2=0.9，首步
step = 1.0 / np.sqrt(np.clip(buf2, 1e-10, None))
v_new = np.sqrt(float(((v_mean * red) * step ** 2).sum()))
g = g * (step * (v_norm / v_new))

mask = (g * P) >= 0
P_new = P - lr * g - lr * wd * P * mask
print("g after NorMuon =\n", np.round(g, 6))
print("mask =\n", mask)
print("P after =\n", np.round(P_new, 8))
```

预期输出：

```text
nesterov g = [[0.0975  0.195   0.2925 ]
 [0.04875 0.0975  0.24375]]
g after NorMuon = [[ 0.795947  0.795947  0.22873 ]
 [-0.182029 -0.182029  0.783804]]
mask = [[ True  True  True]
 [False False  True]]
P after = [[-0.00593895  0.00404105  0.0253654 ]
 [ 0.00864058  0.01364058  0.00927391]]
```

三处可以核对的数值：Nesterov 首步的 $\mathbf{g}$ 恰为 $1-\mu^2=0.0975$ 倍原始梯度；NorMuon 缩放前 $\|\mathbf{g}\|_F=\sqrt2$，缩放后仍是 $\sqrt2$（保范数）；掩码在两行各有一组同号/异号，第二行前两列因为更新为负、参数为正而跳过衰减，参数被更新推大。

## 易错点

> [!warning] 具体、可检验的错误
> - 用 $\mathbf{Q}^{\top}\mathbf{Q}=\mathbf{I}$ 检验宽矩阵的正交化结果。$2\times3$ 的更新只有行正交，$\mathbf{Q}\mathbf{Q}^{\top}=\mathbf{I}_2$；$\mathbf{Q}^{\top}\mathbf{Q}$ 是秩 2 投影，迹为 2。
> - 忘记预归一化的 $1.01$ 安全因子。去掉它，$\sigma_{\max}$ 可能接近或超过 1，五次多项式在前两轮会把谱推到 2 以上，bf16 下直接溢出。
> - 认为 Polar Express 收敛到精确的 $\mathbf{U}\mathbf{V}^{\top}$。仓库注释明确说结果是 $\mathbf{U}\mathbf{S}'\mathbf{V}^{\top}$，$\mathbf{S}'_{ii}$ 大约在 $(0.5,1.5)$，例 1 的 $\sigma$ 是 1.033 与 0.966。
> - 以为 NorMuon 的二阶矩有偏差修正。代码没有；保范数修正承担了稳定首步的作用。
> - 把 cautious 掩码的判定写成 `g >= 0`。掩码是 `(g * params) >= 0`，依赖参数符号；只判梯度符号会让负权重在错误的方向上被衰减。
> - 认为所有参数都在 Muon 里。`transformer.h` 之外的 `wte`、`lm_head`、`value_embeds`、标量都在 AdamW；`ve_gate` 虽小却在 Muon 里。
> - 忘记分布式下的补零。$K$ 不被 $N$ 整除时栈末尾要补零张量，回填时必须按 `len(params)` 截断，否则零行会覆盖真实参数。
> - 以为学习率倍数也作用于宽矩阵。`max(1.0, m/n)` 的下界是 1，宽矩阵的倍数恒为 1。

## 关联笔记

- 前置：[[矩阵与线性代数速查]]——SVD、极分解与「最近正交矩阵」引理，是第 1 节全部推导的基础。
- 前置：[[梯度下降与AdamW]]——参数分组、`initial_lr`、调度器与融合核的精度约定，两篇共用同一套机制。
- 后续：05 阶段的分布式训练笔记会展开 `reduce_scatter` / `all_gather` 的三阶段通信，本篇只给出与 Muon 相关的部分。
- 对照：[[优化算法-梯度下降与Adam]]（跨库）——通用的一阶方法与收敛理论，本篇只讲矩阵参数的特殊处理。
- 对照：[[矩阵分解-SVD与特征分解]]（跨库）——SVD 的数值算法与低秩近似，本篇只用到结论。

## 达标检测

- [ ] 证明「谱范数不超过 $\epsilon$ 时 Frobenius 位移最大」的最优解是 $\epsilon\mathbf{U}\mathbf{V}^{\top}$，并说明它和「最近正交矩阵」是同一个矩阵。
- [ ] 写出 Polar Express 的迭代式与 5 组系数的作用，解释为什么要 5 组而不是 1 组。
- [ ] 手推 NorMuon 的保范数性质：证明缩放后 $\|\mathbf{G}'\|_F=\|\mathbf{G}\|_F$。
- [ ] 解释 MuonEq 与 Muon+ 各自修正什么，去掉其一会分别导致什么现象。
- [ ] 验证 cautious weight decay 的掩码方向：对 $W>0,G>0$ 与 $W>0,G<0$ 两种情况分别说明是否衰减、参数如何变化。
- [ ] 列出 d24 的四个 Muon 形状组、张量数与学习率倍数，并算出 `mlp.c_fc` 的有效学习率。
- [ ] 说明单卡与 8 卡下 Muon 的梯度同步、状态保存与参数回填各有什么不同，以及补零的作用。
- [ ] 解释为什么 `wte` 与 `lm_head` 不能进 Muon，而 `ve_gate` 可以。

## 参考来源

- Jordan et al., *Muon: An optimizer for hidden layers in neural networks*（2502.16982）—— 对应动量 + 正交化的总体思想与 $O(\sqrt{\min(m,n)})$ 尺度的更新性质。
- Amsel, Persson, Musco, Gower, *The Polar Express: Optimal Matrix Sign Methods and Their Application to the Muon Algorithm*（2505.16932）—— 对应 5 组系数与五次迭代式，`nanochat/optim.py` 的注释直接引用该编号。
- arXiv 2510.05491（NorMuon）—— 对应正交化之后的逐神经元方差缩放与保范数修正。
- arXiv 2411.16085（Cautious Weight Decay）—— 对应「仅在同号时衰减」的掩码规则。
- Karpathy, *nanochat* `nanochat/optim.py` 与 `nanochat/gpt.py`（commit 92d63d4）—— 对应 `muon_step_fused` 的逐段实现、按形状分组与学习率倍数。
- Karpathy, *modded-nanogpt* —— `nanochat/optim.py` 头部注明 Muon 实现改编自该仓库，对应融合核与参数栈的组织方式。
