math-skill 1.0.0 → 2.0.1

package/references/books/micro-lie-theory.md

@@ -0,0 +1,112 @@
+# 🌀 李理论速成 / A micro Lie theory
+
+> **A micro Lie theory for state estimation in robotics** — Joan Solà, Jeremie Deray, Dinesh Atchuthan.
+> arXiv:1812.01537v9 [cs.RO]，2021-12-08，正文约 17 页 + 附录公式手册。配套开源 C++ 头文件库 **manif**（<https://github.com/artivis/manif>，实现 SO(2)/SO(3)/SE(2)/SE(3) 及解析雅可比）。
+> 本文件是「激活」蒸馏，**不复述原文**；全保真请回查本地 PDF（见〈深挖入口〉）。
+
+## 概要
+
+这篇文章把庞大的李理论（Lie theory）**蓄意"截肢"**到机器人状态估计够用的最小子集：它甚至不引入李括号（Lie bracket），而是把李代数（Lie algebra）直接降格为同构的向量空间 Rⁿ，让"曲的、非线性的"李群在切空间里变成"平的、线性的"向量代数。一句话主旨：**群上（曲）的几乎所有操作，在李代数（平）上都有精确对应**（Fig. 1）——这正是 inspiration.md 里 Sophus Lie "屠龙刀"的现代用法：屠龙（解微分方程）没成，却成了切菜（线性化非线性）、雕刻（描述对称性）、盖房子（机器人状态估计）的神兵。
+
+真实结构地图：
+- **II. A micro Lie theory（核心）**：A 李群（群公理 + 流形）→ B 群作用 → C 切空间与李代数（hat `^∧` / vee `^∨` 算子）→ D **指数映射** exp/log 与大写 Exp/Log（式 23–24）→ E **加减算子** ⊕/⊖（式 25–28，分左右版本）→ F **伴随** Ad_X 与伴随矩阵（式 30–35）→ G **李群上的导数**：右雅可比（式 41a–c）/左雅可比（式 44）→ H **流形上的不确定性与协方差传播**（式 52）→ I 流形上的离散积分。
+- **III. 流形微分法则**：A 链式法则、B 基本雅可比块、C 派生雅可比块。
+- **IV. 复合流形（composite manifolds / bundles）**：把异构大状态拼成非交互流形块，逐块求导（式 84–90，Ex. 7 对比 SE(n) vs T(n)×SO(n) vs ⟨Rⁿ,SO(n)⟩）。
+- **V. 应用**：基于路标的定位与建图——流形上误差状态卡尔曼滤波（式 92–96）、图优化 SLAM、传感器自标定。
+- **VI. 结论 + 附录**：S¹/SO(2)/SE(2)、S³/SO(3)、SE(3) 的全套闭式公式（含右/左雅可比，如 SO(3) 式 143–145）。
+
+## 可迁移到 AI/Infra 的核心结构
+
+论文把"曲的非线性群"和"平的线性向量空间"用五件工具焊在一起，每件都能原样搬进可微算法。
+
+### 1. exp/log 映射 → 流形参数化（式 23–24，Fig. 1）
+
+`Exp: Rⁿ → M`、`Log: M → Rⁿ` 是流形与其切空间（同构于线性 Rⁿ）之间的双射桥梁。迁移用法：**让网络在无约束的切空间 Rⁿ 里自由预测，再经 Exp 投回合法流形**。旋转、位姿、单位四元数因此天然满足约束（正交、单位范数），免去对回归出的矩阵/四元数做事后正交化或归一化的各种 ad-hoc 修补。
+
+### 2. ⊕/⊖ 加减算子 → 流形上的"向量代数"（式 25–28）
+
+`⊕`（一次 Exp + 一次群合成）让"给流形状态加一个增量"写得像普通向量加法；`⊖` 求两元素之差（测地残差）。**关键陷阱**：因群合成不可交换，⊕/⊖ 分**右版本**（增量在局部坐标系/切于 X）与**左版本**（增量在全局坐标系/切于单位元 E），论文默认用右版本——工程里必须全程统一，混用即出错。
+
+### 3. 右/左雅可比 → 反向传播的几何正确版（式 41a–c、44）
+
+流形函数对切空间扰动的线性化即雅可比；流形上的链式法则形如 `D(g∘f)/DX = J_g · J_f`（§III-A），与欧式链式法则同构，故可直接接进自动微分。**右雅可比**（式 41）与**左雅可比**（式 44）描述的是局部 vs 全局切空间的同一导数，二者由伴随 Ad 互相转换。
+
+### 4. 伴随矩阵 Ad_X → 跨坐标系搬运切向量（式 30–35）
+
+`Ad_X` 把同一切向量在不同点、左右坐标系之间搬运（式 32：`X ⊕ τ = (Ad_X τ) ⊕ X`）。它是**等变性的代数实现**，也是扰动/协方差跨坐标系传播的转换矩阵；Ex. 6 给出 SE(3) 的闭式伴随矩阵。
+
+### 5. 协方差传播 → 流形上的不确定性（式 52）
+
+`Σ = E[(X⊖X̄)(X⊖X̄)ᵀ] ∈ Rᵐˣᵐ` —— **协方差活在切空间 Rⁿ 而非群上**。直接在群上定义方差是病态的；切空间表示让卡尔曼滤波/因子图的不确定性运算回到熟悉的线性代数。
+
+此外两件直接可用的"零件"：
+- **SE(3) / SO(3)**：刚体运动群 / 旋转群——位姿（pose）= 旋转 + 平移的统一可微表示，是相机、点云、机械臂关节的标准语言。
+- **复合流形（composite manifolds / bundles，式 84–90）**：把多位姿 + 特征 + 标定等异构大状态拼成非交互流形块，雅可比**逐块组装**（式 89 为块结构化稀疏），即工程上"按块拼雅可比矩阵"。
+
+## 适合激活的问题类型
+
+- 预测/回归量带**几何约束**：旋转、位姿、单位向量、SPD 矩阵——硬塞进欧式 MLP 会破坏约束。
+- 需要**等变性 / 不变性**：输入做刚体变换，输出应协变或不变（点云、分子、多视几何）。
+- 需要**显式不确定性**：位姿估计、传感器融合、SLAM、视觉里程计的协方差传播。
+- **迭代式几何优化**：相机/点云配准（registration）、BA、IK，要在流形上做梯度/高斯牛顿而非欧式空间。
+- 状态在**李群上演化**：惯性预积分、运动模型、可微物理/控制。
+
+## 可能的算法启发
+
+- **SE(3)/SO(3) 等变网络**：以群元素为隐状态，层间用 Exp/⊕ 更新、用 Ad 搬运特征；等变性来自群作用而非数据增强。
+- **流形损失（manifold loss）做位姿回归**：用 ⊖（测地误差）当 loss，而非对旋转矩阵/四元数做欧式 MSE；天然处理流形拓扑（如四元数双覆盖）。
+- **李群优化器**：把 Adam/高斯牛顿改写成"切空间求梯度 → Exp 回投"的 retraction 形式（误差状态 error-state 思路，对应论文 §V-A 的流形 EKF）。
+- **可微配准 / 对齐**：相机位姿、点云 ICP、多视 BA 写成 SE(3) 上的可微优化层，端到端训练。
+- **流形参数化输出头**：网络出 Rⁿ 切向量，Exp 投回 SO(3)/SE(3)，替代 6D/9D 旋转表示的各种 ad-hoc 正交化。
+- **不确定性感知融合**：用式 52 的切空间协方差 + Ad 传播，做可学习的卡尔曼/因子图层。
+
+## GPU 友好性警告
+
+> 验收门唯一权威：[`../gpu-friendly-math.md`](../gpu-friendly-math.md)（八维：①张量化 ②GEMM 可映射 ③复杂度 ④显存/KV ⑤低精度稳定 ⑥并行与通信 ⑦稀疏结构 ⑧算子融合）。逐维打分如下。
+
+| # | 维度 | 评级 | 说明 |
+|---|---|---|---|
+| ① | 张量化 | ✅ | SO(3)/SE(3) 的 exp/log 有**闭式**（Rodrigues），3×3/4×4 小矩阵，批量化为 `[B,3,3]` / `[B,4,4]` 张量逐样本独立 |
+| ② | GEMM 可映射 | ⚠️ | 3×3/4×4 太小，**吃不满 Tensor Core**，bmm/批量小 GEMM 利用率低、易受访存带宽限制；改造：把 batch 维堆大、用专用小核或 einsum 融合 |
+| ③ | 复杂度 | ✅ | 每元素 O(1)，随 batch 线性 |
+| ④ | 显存 | ✅ | 元素极小；但高自由度复合状态的雅可比/协方差矩阵会变大（块结构，仍可控） |
+| ⑤ | 低精度稳定 | ❌ **重点** | exp/log 含 `sinθ/θ`、`(1−cosθ)/θ²` 等项，在 **θ→0**（除零）与 **θ→π**（log 奇异）处灾难性抵消；fp16/bf16 极易 NaN。**必须**对小角做 Taylor 展开切换——而分支会带来 warp divergence（伤①⑧） |
+| ⑥ | 并行与通信 | ⚠️ | 逐样本 exp/log 是 embarrassingly parallel ✅；但**流形上的离散积分/运动链**（§II-I，连乘 Exp）是**串行递推**，长序列需写成并行扫描（parallel scan）才能并行 |
+| ⑦ | 稀疏结构 | ✅ | 复合流形的雅可比是**块结构化稀疏**（式 89），对 GPU 友好 |
+| ⑧ | 算子融合 | ✅ | 闭式 exp/log/雅可比可融进**单 kernel**，避免物化中间小矩阵 |
+
+**展开说明（闭式 vs 级数 / 批量化 / 小矩阵指数能否张量化）**：
+
+李理论里 `exp/log` 的 GPU 命运，完全取决于"是否落在有闭式的低维群上"。
+
+- **闭式 vs 级数（结论 1）**：SO(3) 的指数映射就是 **Rodrigues 公式** `exp([θ]×) = I + (sinθ/θ)[θ]× + ((1−cosθ)/θ²)[θ]ײ`（Ex. 4），SE(3) 类似带一个左雅可比因子 V(θ)——都是**有限项闭式**，纯张量代数、逐样本独立、无数据相关循环。反面是**通用矩阵指数**：任意李群没有 Rodrigues 式闭式，只能 Taylor 级数 + scaling-and-squaring **迭代**逼近，步数数据相关、控制流发散、难张量化，是典型"美但不可算"。闭式只属于 SO(3)/SE(3)/SE(2)/S¹/S³ 这一小撮，**别把通用 matrix exp 当成廉价 O(1) 算子**。
+- **批量化（结论 2）**：把 N 个旋转/位姿堆成 `[B,3,3]` / `[B,4,4]` 做批量 Exp/Log，是干净的 element-wise + 小 bmm，可与下游算子**融合进单 kernel**。小矩阵指数**能**张量化——批量堆叠即逐样本并行；但 3×3/4×4 太小，bmm 吃不满 Tensor Core，价值在"可批量、可融合"而非"打满算力"，想提利用率就把 batch 堆大或用专用小核。
+- **低精度奇异点（结论 3，头号风险）**：θ→0（`sinθ/θ` 除零）与 θ→π（log 不唯一）会灾难性抵消，fp16/bf16 直接 NaN。低精度训练前**必须**对小角做 Taylor 兜底并做确定性复现测试；兜底分支又会引入 warp divergence，需用 `where`/掩码而非数据相关跳转实现。
+- **串行递推**：流形上的运动链/离散积分（§II-I）是连乘 Exp 的串行递推，长序列要改写成并行扫描（parallel scan）才能喂满 GPU。
+
+## 该调用哪个思想武器
+
+- **⚛️ symmetry-invariance（首选）**：李群本就是**连续对称变换群**，本文是"对称/不变性→等变网络"最直接的数学弹药。
+- **🔄 transformation（首选）**：exp/log 把"曲的非线性流形"等价变换到"平的线性切空间"——把难问题变换成易问题的范式样板（屠龙刀"切菜"）。
+- **⚖️ optimization**：流形上的优化、retraction、误差状态滤波（§V-A）。
+- **🌉 modeling**：现实（机器人/相机状态+噪声）→数学（流形+协方差）→解释的建模闭环。
+- **🧩 abstraction**：从具体矩阵/四元数抽象出"群"的统一接口（论文正文泛型 + 例子接地的写法本身就是抽象示范）。
+
+## 反模式
+
+- **在欧式空间直接加减旋转/位姿**：对旋转矩阵/四元数做欧式 MSE 或线性插值——破坏流形约束，应改用 ⊕/⊖ 与测地误差。
+- **左右扰动混用**：右雅可比/左雅可比、局部/全局坐标系约定不统一，导致协方差与梯度错位（论文反复强调默认用右版本）。
+- **误以为 matrix exp 处处廉价闭式**：闭式只属于 SO(3)/SE(3) 等少数群；一般群得迭代级数，不可当作 O(1) 算子。
+- **低精度下不处理奇异点**：θ→0/π 不做 Taylor 兜底，fp16 训练直接 NaN。
+- **把 SE(3) 当成 T(3)×SO(3)**：二者切空间参数化不同（Ex. 7），平移-旋转是否耦合会改变雅可比，误用导致系统性偏差。
+- **过度套用**：不需要不确定性传播/几何约束的任务硬上李理论，徒增复杂度与奇异点风险——数学美 ≠ 该用。
+
+## 深挖入口
+
+> 全保真回查 = 让 Agent 自动检索本地 PDF：`math_book/A micro Lie theory.pdf`（用 `pdftotext` 或 Read PDF pages）。下列为该 PDF 内的真实章节/公式块定位：
+
+1. **§II-D 指数映射 + Fig. 1**：exp/log 与大写 Exp/Log 算子（式 23–24）——流形↔切空间桥梁与闭式来源；配 Ex. 3（SO(3) 的李代数 `[ω]×`）、Ex. 4（SO(3) 的 exp = Rodrigues）。
+2. **§II-E 加减算子（式 25–28）+ §II-F 伴随 Ad_X（式 30–35）**：流形上的"加/减"与左右扰动互转；Ex. 6（SE(3) 的伴随矩阵）。
+3. **§II-G 李群上的导数 + §III-A 链式法则**：右雅可比（式 41a–c）、左雅可比（式 44），二者由伴随相联——反传/梯度的几何正确形式。
+4. **§II-H 流形上的不确定性与协方差传播（式 52）**：Σ 定义在切空间；§V-A 流形误差状态 EKF（式 92–96）是落地范例。
+5. **附录公式手册**：SO(3) 右/左雅可比闭式（式 143–145）、SE(3) 雅可比（引 Barfoot），以及 §IV 复合流形逐块雅可比（式 84–90，Ex. 7）——工程实现直接查表，对照 manif 库。

package/references/books/optimization-ml.md

@@ -0,0 +1,160 @@
+# ⚙️ 最优化（含 ML 应用）/ Optimization with ML
+
+> **An Introduction to Optimization, With Applications to Machine Learning** (5th Edition, 2024)
+> Edwin K. P. Chong, Wu-Sheng Lu, Stanisław H. Żak — John Wiley & Sons（Hardback ISBN 9781119877639）
+>
+> 本文件是「激活参考」：综合提炼、面向工程，不逐字摘录。
+> 目标——把这本经典优化教材里**能落到算法 / GPU / 训练 Infra** 的结构抽出来。
+
+## 概要
+
+经典连续优化教材的第五版。相较旧版，最大增量是新增完整的 **Part V「机器学习中的优化」**，把一阶/二阶最优性、对偶、KKT、收敛性与 SGD/SVM/PCA 等训练实践彻底打通。全书 31 章，分五部分。
+
+真实章节地图：
+
+- **Part I — 数学复习（Ch 1–5）**
+  - Ch 1 证明方法与记号；Ch 2 向量空间与矩阵（秩、内积与范数）。
+  - Ch 3 变换：特征值/特征向量、正交投影、二次型 §3.4、矩阵范数 §3.5。
+  - Ch 4 几何：超平面、**凸集 §4.3**、多胞形与多面体。
+  - Ch 5 微积分：导数矩阵 §5.3、**水平集与梯度 §5.5**、Taylor 级数 §5.6。
+- **Part II — 无约束优化（Ch 6–14）**
+  - Ch 6 局部极小的一阶/二阶必要与充分条件。
+  - Ch 7 一维搜索：黄金分割、Fibonacci、二分、Newton、割线、线搜索。
+  - **Ch 8 梯度法**（最速下降 §8.2、收敛分析 §8.3）。
+  - **Ch 9 Newton 法**（Levenberg–Marquardt §9.3、非线性最小二乘）。
+  - Ch 10 共轭方向/共轭梯度；**Ch 11 拟牛顿**（逆 Hessian 近似、DFP §11.4、**BFGS §11.5**）。
+  - Ch 12 解线性方程（最小二乘、RLS、Kaczmarz、最小范数解）。
+  - **Ch 13 神经网络与反向传播**（单神经元训练 §13.2、Backprop §13.3）。
+  - Ch 14 全局搜索：Nelder–Mead、模拟退火、PSO、遗传算法。
+- **Part III — 线性规划（Ch 15–19）**
+  - Ch 15 LP 基础与几何；Ch 16 单纯形法。
+  - **Ch 17 LP 对偶**（对偶 LP、矩阵博弈）。
+  - Ch 18 非单纯形/内点法（Khachiyan、仿射尺度、Karmarkar）；Ch 19 整数规划。
+- **Part IV — 非线性约束优化（Ch 20–25）**
+  - Ch 20 等式约束：切空间/法空间 §20.3、**Lagrange 条件 §20.4**、二阶条件。
+  - **Ch 21 不等式约束与 KKT**（KKT §21.1、二阶条件 §21.2）。
+  - **Ch 22 凸优化**（凸函数 §22.2、凸问题 §22.3、SDP/LMI §22.4）。
+  - **Ch 23 Lagrange 对偶**（弱/强对偶、对偶间隙 §23.4.6、Slater §23.6.3、鞍点）。
+  - Ch 24 约束算法（投影 §24.2、**投影梯度 §24.3**、Armijo §24.4.4、增广 Lagrange §24.5、惩罚法 §24.6）。
+  - Ch 25 多目标 / 鲁棒 LP（Pareto、不确定性）。
+- **Part V — ML 中的优化（Ch 26–31）**
+  - Ch 26 特征工程、PCA、SVD、线性自编码器。
+  - **Ch 27 SGD 算法**（SGD §27.1、方差缩减 **SVRG §27.2**、**分布式 SVRG 与通信/计算权衡 §27.3**）。
+  - Ch 28 线性回归（正则化 §28.3、交叉验证）；Ch 29 逻辑回归 / Softmax。
+  - **Ch 30 SVM**（hinge loss、硬/软间隔）；**Ch 31 核技巧与 K-Means**。
+
+## 可迁移到 AI/Infra 的核心结构
+
+- **一阶最优性 + 梯度几何（Ch 6, §5.5）**
+  - 梯度 ⊥ 水平集、是最速上升方向——所有训练优化器的公理根。
+  - `∇f = 0` 是停机判据；鞍点 / 非凸是现代深度学习的核心痛点。
+- **收敛性分析框架（Ch 8 §8.3）**
+  - 用条件数 κ = λ_max/λ_min 刻画最速下降的收敛速率。
+  - 解释"为什么病态网络难训、为什么要归一化 / 预条件"。
+- **二阶曲率与阻尼（Ch 9）**
+  - Newton 用 Hessian 给出仿射不变的步长与方向。
+  - Levenberg–Marquardt 的 `(H+μI)` 阻尼 = 信赖域思想，是 Adam 的 `ε`、二阶优化器的祖先。
+- **拟牛顿低秩更新（Ch 11）**
+  - BFGS/DFP 只用梯度差，以 rank-1/rank-2 更新维护逆 Hessian 近似。
+  - 是 L-BFGS、K-FAC、Shampoo 的直接思想源。
+- **无矩阵二阶（Ch 10）**
+  - 共轭梯度只需 Hessian-向量积，不存全 Hessian；对应 autodiff 的 HVP（Hessian-free）。
+- **约束几何（Ch 20–21, 24）**
+  - 切/法空间 → Lagrange/KKT → 投影梯度 + 惩罚 / 增广 Lagrange。
+  - 构成"带约束训练"的完整工具链。
+- **对偶与鞍点（Ch 17, 23）**
+  - 强对偶 ⇔ minimax = maximin；KKT、互补松弛、Slater 条件。
+  - min-max 训练（GAN / 对抗鲁棒）、SVM 对偶都落在这里。
+- **随机与分布式（Ch 27）**
+  - SGD 的无偏梯度估计、SVRG 方差缩减。
+  - **分布式下"通信 vs 计算"的显式权衡**——数据并行训练的理论根。
+- **低秩 / 谱（Ch 26, §3.4）**
+  - SVD/PCA/线性自编码器、二次型与谱——LoRA、KV 压缩、谱归一化的数学底座。
+
+## 适合激活的问题类型
+
+- 选型 / 设计优化器，或解释训练动力学（为什么发散、震荡、停滞在鞍点）。
+- 诊断病态与慢收敛：用条件数 κ 把"难训"量化。
+- 带约束训练：权重范数球、谱范数、安全 / 预算约束，需要投影或惩罚。
+- min-max / 对抗 / 对偶视角：把难解 primal 换成易解 dual（如核 Gram 矩阵）。
+- 分布式训练的通信-计算权衡、梯度压缩、方差缩减。
+- 需要二阶信息却不能算全 Hessian 的场景（曲率自适应预条件）。
+
+## 可能的算法启发
+
+- **自适应优化器**
+  - Levenberg–Marquardt 的 `(H+μI)` 阻尼 → Adam 的 `ε`、信赖域、自适应学习率。
+  - 把"曲率 / 阻尼"显式化，而非停留在纯启发式调参。
+- **大模型可行的二阶**
+  - L-BFGS：只存最近 m 步梯度对（低秩历史，显存 O(md)）。
+  - Hessian-free：autodiff 的 HVP + CG（matrix-free，无需物化 Hessian）。
+  - K-FAC / Shampoo：把 Hessian 近似成**块对角 / Kronecker 因子**，每块退化为小 GEMM。
+- **对偶视角高效求解**
+  - SVM 把高维 primal 转成只依赖核 Gram 矩阵的对偶（Ch 30–31），样本数 ≪ 维度时大赚。
+  - 约束问题的对偶分解天然可并行。
+- **约束训练**
+  - 投影梯度（§24.3）做 norm-ball / spectral-norm 约束（weight clipping、谱归一化）。
+  - 增广 Lagrange / 惩罚法（§24.5–24.6）把硬约束软化成可微正则。
+- **方差缩减 / 大 batch**
+  - SVRG（§27.2）的控制变量思想 → 梯度累积、大 batch 训练的稳定性分析。
+- **分布式**
+  - §27.3「通信 vs 计算」直接对应 all-reduce 与计算的 overlap、梯度压缩、联邦 / 数据安全。
+
+## GPU 友好性警告
+
+> 以下逐项对照 `../gpu-friendly-math.md` 的**八维记分卡**（先读它）。
+> 结论：本书的一阶 / 随机 / 低秩部分天然友好；二阶法与搜索类方法需重度改造或淘汰。
+
+- **二阶法的全 Hessian（Ch 9, 11）**
+  - 违反**维度 4（显存）**：稠密 Hessian 是 O(d²)，亿级参数无法物化。
+  - 违反**维度 2（GEMM 可映射）**：求逆 / 分解非 batched-GEMM 友好。
+  - 违反**维度 5（低精度稳定）**：病态求逆在 bf16/fp16 灾难性抵消。
+  - 改造：matrix-free HVP + CG、L-BFGS 低秩、K-FAC 块对角 → 重回**维度 2/4** 友好。
+- **线搜索（Ch 7 黄金分割 / Armijo §24.4.4）**
+  - 违反**维度 1（张量化）**：本质是标量循环 + 数据相关分支（逐步比较函数值）。
+  - 违反**维度 8（算子融合）**：频繁小 kernel、控制流发散。
+  - 改造：大模型几乎都用调度式步长（warmup + cosine）替代逐步线搜索。
+- **一阶 / SGD（Ch 8, 27）**
+  - **维度 1/2 友好**：梯度 = 张量代数、可写成 GEMM。
+  - **维度 6（并行与通信）**良好：数据并行 all-reduce 可与反向 overlap——大模型默认路线的根本原因。
+- **全局搜索（Ch 14：GA/SA/PSO）**
+  - 违反**维度 1**：不可微、离散随机搜索，阻断端到端梯度训练。
+  - **维度 6** 也差：种群间依赖、难并行映射。仅适合黑盒超参搜索，不进训练内环。
+- **LP 单纯形 / 内点法（Ch 16, 18）**
+  - 单纯形的行运算尚可；内点法每步要解线性系统，**维度 2/6** 受限于分解与通信。
+  - 适合中等规模约束子问题，不适合放进每个训练 step。
+- **投影（§24.2）**
+  - norm-ball / box 投影是廉价 elementwise（**维度 1/8** 友好）。
+  - 一般多面体投影要解 QP（**维度 2** 退化）。
+- **收敛依赖条件数 κ**
+  - κ 大 → **维度 5** 在低精度下被进一步放大（病态梯度）。
+  - 必须配归一化 / 预条件，否则 bf16 训练发散。
+
+## 该调用哪个思想武器
+
+- **optimization**（主）：目标-约束-最优性-收敛的完整框架，本书是其核心出处。
+- **algorithmic-thinking**：迭代算法的收敛性、复杂度、步长 / 停机判据。
+- **transformation**：对偶、核技巧、变量替换、SVD/PCA——"等价转换简化问题"。
+- **modeling**：把现实任务（分类 / 回归 / 约束）翻译成可解的优化问题。
+- **probability-statistics**：SGD 随机梯度、SVRG 方差缩减、交叉验证 / 正则化。
+
+## 反模式
+
+- 把**全 Hessian Newton** 直接上大模型——O(d²) 显存与求逆当场爆炸（必须 matrix-free / 低秩 / 块对角）。
+- 在大模型每步用**线搜索**调步长——标量串行、控制流发散，吃光算力；应改调度式学习率。
+- 用 **GA/SA/PSO 训练神经网络**——不可微、无法并行、样本效率极低；仅限黑盒超参搜索。
+- 谈收敛却**忽略条件数 κ**——不归一化 / 不预条件就期望低精度收敛是幻觉。
+- 把 **LP 单纯形思维**硬套连续可微问题。
+- 把**对偶 / KKT 当万能**——非凸通常无强对偶、存在对偶间隙（§23.4.6），KKT 只是必要条件。
+- 把这份「激活参考」当严格证明来源——细节与定理条件必须回查原书。
+
+## 深挖入口
+
+全保真回查 = 让 Agent 直接搜索本地 PDF
+`math_book/An Introduction to Optimization With Applications to Machine Learning.pdf`，按真实章号定位：
+
+- **Ch 8 Gradient Methods**（§8.3 收敛分析、条件数）+ **Ch 11 Quasi-Newton Methods**（§11.5 BFGS）——优化器与可行二阶。
+- **Ch 22 Convex Optimization Problems**（§22.2 凸函数、§22.4 SDP/LMI）——凸性判据与半定规划。
+- **Ch 23 Lagrangian Duality**（§23.5 强对偶、§23.6.3 Slater 条件）+ **Ch 21 KKT Condition**——对偶 / KKT / 鞍点。
+- **Ch 24 Algorithms for Constrained Optimization**（§24.3 投影梯度、§24.5 增广 Lagrange、§24.6 惩罚法）——约束训练算法。
+- **Ch 27 Stochastic Gradient Descent Algorithms**（§27.1 SGD、§27.2 SVRG、§27.3 分布式与通信 / 计算）——大规模训练核心。

package/references/books/smooth-manifolds.md

@@ -0,0 +1,101 @@
+# 🌐 光滑流形 / Smooth Manifolds
+
+> **书目**：John M. Lee, *Introduction to Smooth Manifolds*, 2nd Edition. Graduate Texts in Mathematics 218, Springer, 2013. ISBN 978-1-4419-9981-8 / DOI 10.1007/978-1-4419-9982-5. MSC 53-01 / 58-01 / 57-01.
+> **定位**：把"局部像欧氏空间、整体可弯曲"的对象（manifold）配上微积分（切空间、向量场、微分形式、流、李导数），是 **流形优化、隐空间几何、可微结构** 的数学母体。
+
+## 概要
+
+光滑流形 = 局部能用坐标卡（chart）线性化、卡与卡之间用光滑转移映射（transition map）粘合的空间。全书主线：**先把欧氏微积分搬到弯曲空间上，再研究其上的几何与拓扑不变量**。对 AI 最值钱的是前半部分那套"可微机器"——切/余切空间、向量场、流、黎曼度量。
+
+真实章节地图（2nd ed.，章号与本书一致）：
+
+- **Ch 1–2 Smooth Manifolds / Smooth Maps**：拓扑流形、光滑结构（atlas）、光滑映射、单位分解（partition of unity）。→ 局部线性化 + 全局拼接的语言。
+- **Ch 3 Tangent Vectors**：切空间 T_pM、微分（differential / pushforward）df_p、切丛 TM。→ **局部线性化的核心**，反向传播的几何原型。
+- **Ch 4–5 Submersions, Immersions, Embeddings / Submanifolds**：常秩定理、嵌入、正则水平集 → 子流形。→ 约束集 = 子流形。
+- **Ch 6 Sard's Theorem**：临界值测度为零、Whitney 嵌入定理（n 维流形可嵌入 R^{2n}）。→ 嵌入维数 / 流形假设。
+- **Ch 7 Lie Groups**：既是群又是流形（SO(n), U(n), GL(n), Stiefel…），李代数 = 单位元处切空间。→ 正交/酉权重约束、等变。
+- **Ch 8–9 Vector Fields / Integral Curves and Flows**：向量场、积分曲线、流（flow，单参数微分同胚群）、李导数与李括号 [X,Y]。→ **Neural ODE / 扩散 / 连续归一化流** 的母结构。
+- **Ch 10–12 Vector Bundles / Cotangent Bundle / Tensors**：丛、余向量场（1-form）、拉回（pullback）、张量。→ 梯度的真身是余向量。
+- **Ch 13 Riemannian Metrics**：每点内积、长度/距离/体积、切-余切同构（musical ♯/♭，升降指标）。→ **自然梯度 / 黎曼优化的度量来源**。
+- **Ch 14–16 Differential Forms / Orientations / Integration**：k-形式、楔积、外微分 d（d²=0）、定向、体积形式、流形上积分与变量替换。→ 归一化流的 log-det-Jacobian = 体积形式拉回。
+- **Ch 17–18 De Rham Cohomology / de Rham Theorem**：闭形式模去恰当形式 = 从微分数据读出的拓扑不变量。→ 全局障碍 / 上同调正则。
+- **Ch 19–22 Distributions & Foliations / Exponential Map / Quotient Manifolds / Symplectic Manifolds**：可积分布（Frobenius）、指数映射（retraction 原型）、商流形（Grassmann 等）、辛形式与 Hamilton 流。→ retraction、商空间约束、辛积分器 / HMC。
+
+**作者明示的边界（preface）**：本书止步于"建立工具"，**刻意不讲** connection、geodesic、curvature、纤维丛、Hodge 理论——这些在 Lee 的 *Riemannian Manifolds* 续作里。所以若问题真正需要曲率/平行移动的深层几何，本书只给到度量与指数映射的入口，需另取黎曼几何书续接。
+
+## 可迁移到 AI/Infra 的核心结构
+
+- **切空间 = 参数/隐空间的局部线性化（local linearization）**。`df_p: T_pM → T_{f(p)}N` 就是 Jacobian / pushforward；反向传播 = 沿复合映射做 pushforward（链式法则的几何版）。一切一阶方法都活在切空间里。
+- **梯度是余向量（covector），不是向量**。autodiff 给出的是 1-form（余切空间元素）；要变成可下降的方向（切向量）必须用 **度量升指标**（♯）。欧氏度量 → 普通梯度；Fisher 度量 → 自然梯度（natural gradient）。**这是自然梯度 / 镜像下降的流形根因**。
+- **约束集 = 子流形（submanifold）**。正则水平集定理：当 g 是 submersion 时 `g(x)=c` 的解集是光滑子流形；约束优化 = 在子流形上做无约束优化。
+- **李群 = 可微的对称群**。SO(n)/U(n)/Stiefel/Grassmann 都是流形；其李代数（如反对称矩阵 so(n)）是线性空间，用 `exp` 映射回群 → **把"约束权重"重参数化为"无约束李代数 + exp"**。
+- **流（flow）= 时间参数化的微分同胚族**。学一个向量场 + 沿它积分 = Neural ODE / 连续归一化流 / 扩散采样。流的可逆性、保体积性直接对应模型性质。
+- **黎曼度量 = 可设计/可学习的"局部几何"**。它决定距离、夹角、体积、谁与谁正交；改度量就改了优化轨迹与采样测度。
+- **微分形式 + 体积形式 = 变量替换的语言**。归一化流里的 `log|det J|` 项就是体积形式在映射下的拉回；选对结构（三角/耦合 Jacobian）能让它廉价。
+
+## 适合激活的问题类型
+
+- 参数本应满足 **几何约束**：正交、单位范数、单位行列式、SPD、低秩流形、双曲/球面隐空间。
+- 优化在 **弯曲空间** 上更自然：Stiefel/Grassmann 上的子空间学习、旋转/姿态估计、超球面表征。
+- 需要 **保结构动力学**：可逆生成模型、保体积流、Hamilton 系统、能量守恒的长程模拟。
+- **隐空间几何**：插值、测地线、度量学习、流形上的聚类/最近邻。
+- 需要从相关性升级到 **拓扑不变量**：检测隐空间的"洞"、全局障碍、用上同调做一致性正则。
+
+## 可能的算法启发
+
+- **黎曼/流形优化器（Riemannian optimizers）**：把 Adam/SGD 搬到 Stiefel、Grassmann、SPD、双曲空间——梯度投影到切空间 + retraction 回流形。
+- **正交/Stiefel 约束权重**：用 Cayley 变换或 QR-retraction 维持 `WᵀW=I`，缓解 RNN/深网的梯度爆炸/消失；或用 so(n) 李代数 + matrix-exp 重参数化旋转。
+- **测地线插值（geodesic interpolation）**：在球面/双曲/SPD 隐空间用闭式测地线做插值与混合，替代欧氏线性插值。
+- **流形上的归一化**：把 LayerNorm/特征归一化理解为投影到球面/单位流形；超球面 softmax、谱归一化都是此类。
+- **Neural ODE / 连续归一化流 / 扩散**：学向量场 X_θ，用流求解；结构化 Jacobian 让 `log-det` 廉价。
+- **辛积分器（symplectic integrator）/ HMC**：用 leapfrog 这种保辛、保体积的显式更新做采样与"带动量的优化"，长程稳定。
+- **等变网络（equivariant nets）**：用李群作用 + 商流形把对称性写进结构（geometric deep learning）。
+
+## GPU 友好性警告
+
+> 验收门唯一权威：`../gpu-friendly-math.md` 的 **八维**。流形方法的成败几乎全卡在一个点上：**retraction / 指数映射能不能张量化并 GEMM 化，还是必须迭代求解。**
+
+逐维对照：
+
+- **维度 1–2 张量化 / GEMM**：切空间运算（pushforward/pullback、Jacobian-向量积、把梯度投影到切空间）**天然是 batched GEMM** ✅——反向传播本就是 pushforward，这部分对 GPU 极友好。**但** retraction/exp 多半要 QR、特征分解、矩阵指数或小矩阵求逆：QR/eig **不是干净的 GEMM**，是带串行依赖的分解（cuSOLVER 批量小矩阵尚可，大矩阵 O(n³) 且并行差）→ **可改造** 而非天然友好。
+- **维度 3 复杂度**：测地线距离、平行移动、一般 `log|det J|` 都是 O(n³) 起。**改造**：限定有闭式测地线的流形（球面/双曲/SO(3)）；归一化流用三角/耦合层让 log-det 退化成对角和（O(n)）。
+- **维度 5 低精度**：⚠️ **最大坑**。矩阵 `exp / log / sqrt`、特征分解、SPD 的仿射不变度量在 bf16/fp16 下 **灾难性不稳定**，常静默地需要 fp32/fp64。流形原语经常"表面能跑、数值早已发散"。
+- **维度 6 并行与通信**：scaling-and-squaring 的平方链、ODE 积分步、Householder/QR 都有 **串行递推**，难跨 SM/设备 overlap。反例向好：显式辛积分器（leapfrog）高并行 ✅。
+- **维度 4/7/8 显存 / 稀疏 / 融合**：李代数/旋转参数化若限制在 **小矩阵或块对角**（如逐头旋转、SO(3) 的 Rodrigues 闭式），可融进 kernel、走 Tensor Core；大稠密流形算子则要物化大中间张量。
+
+**结论与改造手法（呼应 gpu-friendly-math.md 工具箱）**：
+
+1. **优先选有闭式 retraction 的流形**（球面、Stiefel-QR、SO(3)、双曲）。
+2. **能软化就软化**：把硬约束换成纯 GEMM 的正则项（如 `λ‖WᵀW−I‖²` 替代严格正交流形）——多数训练这就够。
+3. **小矩阵 / 块化**：把 exp/Cayley/QR 限制在小块或逐头，批量化为 batched GEMM。
+4. **结构化 Jacobian**：归一化流坚持三角/耦合结构，杜绝通用 LU 求 det。
+5. **精度护栏**：凡矩阵 exp/log/eig，强制 fp32 累加并做数值稳定（log-sum-exp 式）。
+
+## 该调用哪个思想武器
+
+- **optimization（⚖️ 优化思想）**：主武器——约束下寻最优、黎曼/流形优化、retraction 选型。
+- **symmetry-invariance（⚛️ 对称与不变性）**：李群、等变、商流形、群作用下的不变量。
+- **transformation（🔄 变换思想）**：坐标卡变换、pushforward/pullback、归一化流的变量替换、微分同胚。
+- **topological-thinking（🌀 拓扑思想）**：de Rham 上同调、全局障碍、隐空间的"洞"与连通性。
+- **abstraction（🧩 抽象化思想）**：从高维杂乱的环境数据中抽出"局部线性 + 光滑拼接"的流形骨架（流形假设）。
+
+## 反模式
+
+- **把 ML 的 "tensor"（数组）当数学 tensor（多线性、有协变/逆变变换律）**，误以为自动获得坐标无关的不变性。
+- **把 exp / 测地线 / matrix-log 放进 bf16 热训练循环**：既慢（串行分解）又静默发散。先问"有没有闭式 retraction / 能不能软化"。
+- **该软不软**：用严格流形约束换来微小收益，却付出 QR/eig 的吞吐与稳定性代价；很多任务一个正交正则项就够。
+- **混淆梯度（余向量）与下降方向（向量）**：忘了度量、把 raw autodiff 输出直接当自然梯度。
+- **单一全局坐标卡的幻觉**：用一套全局参数化覆盖整个流形必有奇点（如欧拉角的 gimbal lock）；流形本质需要 atlas / 冗余参数化。
+- **流形假设滥用**：参数空间本是平坦欧氏时硬套黎曼机器，纯属过度工程（违反 simplicity-first）。
+
+## 深挖入口
+
+> **全保真回查**：需要原文定义/定理/证明时，让 Agent **自动搜索本地 PDF** `math_book/Introduction to Smooth Manifolds.pdf`（按章号/关键词定位，勿凭记忆复述）。下列为真实章号（2nd ed.）：
+
+- **Ch 3 Tangent Vectors** — 切空间、微分/pushforward、切丛：局部线性化与反传的几何原型。
+- **Ch 11 The Cotangent Bundle** — 余向量场（1-form）、`df` 作为余向量、pullback：梯度真身 = 余向量。
+- **Ch 13 Riemannian Metrics** — 度量、切-余切同构（♯/♭）、距离：自然梯度 / 黎曼优化的根。
+- **Ch 9 Integral Curves and Flows** — 流、积分曲线、李导数/李括号：Neural ODE / 扩散 / 保结构动力学。
+- **Ch 20 The Exponential Map** — 指数映射：retraction 原型，也是 GPU 可行性的主瓶颈。
+
+（延伸：Ch 7 Lie Groups → 正交/酉约束与等变；Ch 14 Differential Forms → 体积形式与 log-det-Jacobian；Ch 22 Symplectic Manifolds → 辛积分器 / HMC。）

package/references/gpu-friendly-math.md

@@ -0,0 +1,65 @@
+# GPU 友好性总清单 / GPU-Friendly Math Checklist
+
+> 本文件是「GPU 可行性」验收门的**唯一权威来源（single source of truth）**。
+> activator、16 个思想武器、`books/*.md`、以及 `../agents/math-critic.md` 都引用此处，不重复定义。
+>
+> This file is the single source of truth for the "GPU-feasibility" acceptance gate. The activator, the 16 weapons, the book references, and the math-critic all point here.
+
+## 核心命题 / Core Proposition
+
+**数学美 ≠ 可算。** 一个结构要真正进入现代 GPU 集群的训练与推理，必须同时满足两件事：
+
+1. **数学正确（beautiful in math）**——结构自洽、可微（或可松弛为可微）、有正确性保证。
+2. **硬件可行（friendly to GPU）**——能高效映射到 GPU 微架构（Tensor Core、显存层级、并行与互连）。
+
+许多"看上去很美"的现代数学结构，一遇到 GPU 的并行计算与低精度数制误差就无法高性能运行。本清单就是把"GPU 可行性"变成**可逐项打分**的工程标准，避免把不可算的东西当成果。
+
+## 八维检查 / The 8-Dimension Scorecard
+
+对任何候选结构（算子、注意力变体、路由、正则项、压缩方案……）逐项评 `友好 / 可改造 / 不友好`，并给出改造建议。
+
+| # | 维度 | 关键问题 | 友好 ✅ | 不友好 ❌ |
+|---|------|---------|--------|----------|
+| 1 | **张量化 / Tensorization** | 能否表达为稠密张量运算，避免逐元素不规则控制流？ | 批量张量代数 | 标量循环、数据相关分支 |
+| 2 | **GEMM 可映射 / GEMM mappability** | 能否落到 矩阵乘 / batched GEMM / 卷积，吃满 Tensor Core？ | 可写成 GEMM 链 | 无法矩阵化的不规则运算 |
+| 3 | **复杂度 / Complexity** | 前向/反向是否亚二次？随序列/规模如何增长？ | 线性/亚二次、可分块 | O(n²) 起的显存/算力爆炸 |
+| 4 | **显存与 KV-Cache / Memory** | 峰值显存、激活/状态/KV 占用；能否压缩？ | 低秩/量化/块摘要可压 | 必须物化巨大中间张量 |
+| 5 | **低精度稳定 / Low-precision** | fp16/bf16/fp8 下是否稳定、可确定性复现？ | 动态范围可控、数值稳健 | 灾难性抵消、病态、需 fp64 |
+| 6 | **并行与通信 / Parallelism** | 能否跨 SM/设备并行？通信 vs 计算、能否 overlap？ | 高并行、通信可 overlap | 长串行递推、通信瓶颈 |
+| 7 | **稀疏结构 / Sparsity** | 是结构化还是非结构化稀疏？ | 块/带状结构化稀疏 | 随机 gather/scatter |
+| 8 | **算子融合 / Kernel fusion** | 能否融合、避免物化大中间量（FlashAttention 式）？ | 可融合、可重计算 | 频繁小 kernel、发散控制流 |
+
+**评分结论**：只保留**数学美 AND（八维全部友好或可改造）**的候选；任何一维"不友好且不可改造"，要么改造、要么淘汰。
+
+## 常见「美但不可算」反模式 / Anti-Patterns
+
+- **稠密全局算子 O(n²)**：朴素 softmax 注意力随上下文爆炸。
+- **非结构化稀疏 / 不规则图遍历**：随机访存毁掉访存局部性。
+- **高精度依赖**：病态问题，需 fp64 才正确（绝大多数训练只有 bf16/fp16/fp8）。
+- **串行递推**：长程依赖无法并行（朴素 RNN 式）。
+- **频繁小 kernel + 控制流发散**：启动开销与 warp divergence 吃掉算力。
+- **不可微 / 需离散搜索**：阻断端到端梯度训练。
+
+## 改造手法 / Make-It-Computable Toolkit
+
+把"美但不可算"改造成"既美又可算"的常用招式：
+
+- **离散 → 连续松弛**：Gumbel-softmax；**热带半环（tropical semiring）上的分段线性**门控替代硬 Top-K。
+- **块稀疏化**：块内 dense attention、块间结构化 sparse（如 DeepSeek CSA 式分块）。
+- **低秩 / 投影压缩**：限制映射（restriction map）用低秩线性变换；**低秩基底式块摘要**压缩 KV-Cache（存基底而非 Plücker 坐标——后者低秩时反扩张）。
+- **数值重参数化**：log-sum-exp、归一化、稳定 softmax，保证低精度稳定。
+- **算子融合 / 重计算**：融合 kernel、activation recompute 省显存。
+- **结构嵌入 GEMM**：把代数/几何变换写成**可学习线性映射**，使其天然落到 Tensor Core。
+
+## 范例对照：Tropical Sheaf Attention / Worked Example
+
+来自 `agentic-workflow.md` 引用的 auto-research 方向，演示一个**候选设计如何进入八维验证**：
+
+| 组件 | 数学来源 | GPU 友好性 |
+|------|---------|-----------|
+| 热带门控 Tropical Gating | 热带半环分段线性 | 替代 Top-K：逐元素 max-plus——dim 1 ✅ 张量化 / dim 2 ❌ 非 Tensor Core GEMM（落 CUDA core）/ dim 3 ✅ 仅逐 token 门控亚二次（min-plus matmul 则 APSP-hard 非亚二次）；次可微，折点需 LogSumExp 软化（软化退回标准 softmax）|
+| 胞腔层扩散 Cellular Sheaf Diffusion | 代数几何/拓扑（层、限制映射）| 每边低秩线性变换 = 小 GEMM（维度 2/4）|
+| Čech 上同调正则 | 代数拓扑（一阶上同调 H¹）| 局部、廉价；作幻觉的代数判据（维度 3/8）|
+| 低秩基底 KV 压缩（Plücker/Grassmannian 视角） | 射影几何 | 存基底而非 Plücker 坐标（后者低秩时反扩张）；块摘要候选，压缩率/误差/吞吐需实测（维度 4）|
+
+使用时不要把上表当作已验证结论。正确做法是把每个组件写进 testplan：证明或估计复杂度，测峰值显存和吞吐，检查 bf16/fp8 稳定性，确认能否落到 GEMM / batched GEMM / fused kernel。只有实测和推导都通过后，才标为 "math beautiful × GPU friendly"。