Files
marqdo/doc/design/ext-linalg-formula-doc.md
cflmyandCursor 687c168014 feat(parse): use nested YAML import: maps instead of one-liner binds
Frontmatter imports are now valid YAML (`import:` / `导入:` with bind→target
entries), removing spaced keys. Add `marqdo migrate imports`, hard-error the
old one-liner form, and migrate lib/ext/examples/tests/docs accordingly.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 19:33:58 +08:00

237 lines
8.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# `ext/linalg` — 公式文档面(跑通即正确)
| | |
|---|---|
| 状态 | **Draft · 锁定作者面哲学与分期** |
| 日期 | 2026-09-07 |
| 父设计 | [ext-linalg.md](ext-linalg.md) |
| 路线图 | [roadmap/ext-linalg.md](../roadmap/ext-linalg.md) |
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
| 对照 | [stdlib-math.md](stdlib-math.md)(高中标量公式) |
---
## 0. 一句话
**`.mq.md` 里的线性代数应当读起来像一份可运行的公式讲义**:式子能跑通,就在库承诺的规则与维数下代表正确;`lib/math` 守高中边界,大学符号矩阵与更深层计算由 **`ext/linalg` 正当承担**。
---
## 1. 产品哲学
### 1.1 与 Marqdo 总原则对齐
| Marqdo | 在线性代数上的含义 |
|--------|-------------------|
| 代码即文档 | 矩阵代数段落用数学式书写,而不是 API 调用清单 |
| 标记即语法 | `$$`、中缀、`# matrix` 方法都是可读标记,不是「库胶水」 |
| 跑通可验收 | 金样 / 课堂作业:文件 exit 0 + 断言化简结果 = 式子合法 |
### 1.2 「跑通即正确」的精确定义
**不是**「任意高深定理自动证明」。
**是**在声明的能力边界内,下列任一成立则文档该段视为正确:
1. **形状层**:不相容维数的乘加在构造时硬错误(写不出可运行的坏式)。
2. **恒等式层**:文档断言的规范形(如 `(AB)^\top → B^\top A^\top`)经规则集得到。
3. **数值核对层**(可选):小 `$$` 数值阵 `explicit` 后与手算一致——验算,不是符号证明。
更高深主题(矩阵微积分、表示、特殊函数矩阵等)通过**扩展同一公式面的规则表**分期加入,而不是另起一套函数库叙事。
### 1.3 与 `lib/math` 的边界(再次锁定)
| | `lib/math` | `ext/linalg` |
|--|------------|--------------|
| 教育边界 | 高中标量公式 | 大学经典线性代数及更深(官方 ext) |
| 值类型 | `Value::Formula`(标量 AST) | `_type=matrix` / `矩阵`(MatExpr + 稠密) |
| 作者感觉 | `$$sin(x)+x$$` + `diff` / `plot` | `A*B`、`(AB)^T`、分块、分解图 |
| 是否「数学库」 | 是(stdlib) | **是数学库的官方扩展**,不是旁路工具箱 |
把大学 LA 塞进 `lib/math` ❌;在 `ext/linalg` 做大学符号计算乃至更深 ✅。
---
## 2. 两面模型:代数面 vs 计算面
文档里应能一眼分清「推导」与「动手算」。
### 2.1 代数面(默认;公式文档)
| 意图 | 写法(目标) | 语义 |
|------|--------------|------|
| 引入符号阵 | 见 §3 | 惰性 `MatrixSymbol` |
| 加减乘 | `` `C` = `A` + `B` `` · `` `P` = `A` * `B` `` | 建树 + 形状检查 |
| 转置 / 逆 | `` `At` = > `A`.T `` · `` `Ai` = > `A`.inv `` | 惰性节点 |
| 化简 / 展示 | 见 §4(默认化简策略) | 规则不动点 → ASCII / KaTeX |
| 分块 / Kronecker | 表或 `block` / `kron`(可保留具名,但结果仍是公式) | 惰性 |
**读者感受**:像在抄黑板,而不是在调 `la.mul`。
### 2.2 计算面(显式步骤;可单独成段)
| 意图 | 写法 | 语义 |
|------|------|------|
| 稠密求值 | `` `E` = > `A`.explicit `` / `la.explicit` | 展开数值 |
| 分解 | `` `f` = > la.factorize matrix=`A` kind="svd" `` | `linalg_factor` |
| 求解 / 最小二乘 | `solve` / `lstsq` | 数值解 |
| 度量 | `norm` / `cond` / `rank` / `det`(数值路径) | 标量或条件对象 |
| 作图 | `draw` / `show` | SVG / 公式卡 |
**读者感受**:「于是我们计算 / 画出…」——与纯代数叙述分段书写。
---
## 3. 目标作者语法(公式文档优先)
### 3.1 已落地(v1 中缀 / 方法)
```markdown
*`A` = > la.symbol name="A" rows=2 cols=2*
*`B` = > la.symbol name="B" rows=2 cols=2*
*`C` = `A` + `B`*
*`P` = `A` * `B`*
*`Pt` = > `P`.T*
*`s` = > `Pt`.simplify*
*`t` = > `s`.ascii*
```
数值 `$$` 矩阵可直接参与 `+` / `*`(经插件吸收为稠密叶)。
### 3.2 目标形态(文档感更强;分期实现)
**叙事理想(不必一次做完):**
```markdown
# 正规方程
令 \(A\) 为 \(m\times n\) 设计矩阵,\(b\) 为观测。
*`AtA` = > `A`.T * `A`* # 或未来更紧凑的 postfix / 混合写法
*`xty` = > `A`.T * `b`*
*`xhat` = > `AtA`.solve b=`xty`* # 计算面
```
**符号引入(减少 `la.symbol` 噪音)——候选(F2 选定一种):**
| 候选 | 例 | 利 | 弊 |
|------|----|----|-----|
| A. 构造糖 | `` `A` = > la.matrix name=A rows=m cols=n `` | 已有 `# matrix` | 仍是调用 |
| B. 维数表 | GFM 表声明符号与形状,一行绑定 | 很「文档」 | 需新约定 |
| C. `$$` 符号方言 | `$$A_{m\times n}$$` → MatExpr | 最像讲义 | 解析歧义;勿污染标量 formula |
| D. 保持 `symbol` + 短别名 | `` `A` = > la.A rows=m cols=n `` | 实现便宜 | 文档感一般 |
**锁定倾向:** 短期 **A + 默认化简(F1)**;**F2 采用 B(GFM `@` 表 + `la.declare`)**;受限 C(`$$` 符号方言)仍待评估且不得污染核心 formula。
### 3.3 明确不做(本波语法)
- 把符号 MatExpr 塞进核心 `formula::Expr`
- 发明与 Markdown 列表冲突的行首 `+` 矩阵语法
- 用未定义的 `$$矩阵A$$` 伪方言冒充已实现语义
---
## 4. 默认化简与「写出即规范」
### 4.1 策略
| 操作 | 是否自动 `simplify` | 理由 |
|------|---------------------|------|
| `ascii` / `latex` / `show` | **是(F1 done)** | 展示面应接近讲义规范形;`raw=True` 可关 |
| 中缀 `+` `*` `-` 的构造结果 | **否** | 保留用户书写结构;需要时再化简 |
| `.simplify` | 显式不动点 | 文档断言 / 金样 |
| `explicit` 前 | 可选先 simplify(F1.1) | 减少无效稠密路径 |
### 4.2 验收句式(金样)
```markdown
*`P` = `A` * `B`*
*`Pt` = > `P`.T*
*`t` = > `Pt`.ascii* # F1:无需再 .simplify 即得 B^T*A^T
1. `t` == "B^T*A^T"
> print text=ok
```
「跑通 + 断言」= 这段公式文档正确。
---
## 5. 正确性分层与错误体验
| 层 | 失败时 | 作者应看到 |
|----|--------|------------|
| 形状 | `A*B` 列行不配 | 含双方 shape 的硬错误,指向调用点 |
| 规则 | 无法化到文档期望形 | 金样失败;或 `ascii` 仍为未化简形(需补规则) |
| 插件未加载 | 中缀矩阵运算 | 提示 `ext add linalg` / `ensure_plugin` |
| 超维 | `explicit` / 分解 | 护栏错误,建议保持符号 |
---
## 6. 与实现现状的对照
| 能力 | 状态 |
|------|------|
| MatExpr 惰性树 + R1–R5 / 分块 / kron | done(L1–L3) |
| 稠密 / 分解 / 度量 / draw theme | done(L2–L6) |
| 中缀 `+` `-` `*` + `# matrix` 方法 | done(v1) |
| `ascii`/`latex`/`show` 默认 simplify | **done(F1)** |
| 更少噪音的符号引入 | **done(F2:`declare` + 表)** |
| 更紧凑转置 / 混合公式书写 | **done(F3:`T_ascii`)** |
| `explicit` 前可选 auto-simplify | **done(F3,默认开)** |
| public「如何写公式文档」 | **done(F3)** |
| 矩阵微积分等 | L7+ / 规则表扩展 |
---
## 7. 分期(公式文档面)
| 阶段 | 内容 | 出口 |
|------|------|------|
| **F1** | 展示路径默认 simplify;金样「`.T` + `ascii` → 规范形」;设计本文落地 | **done** |
| **F2** | 符号引入降噪(选定 §3.2 候选);更新 examples 使其读起来像讲义 | **done**(`declare` + `linalg-transpose`) |
| **F3** | 可选 postfix / 链式糖;`explicit` 前可选 auto-simplify;public 短文「如何写公式文档」 | **done** |
| **F4+** | 新规则(伴随、多项式矩阵…);矩阵微积分仅当明确需要 | 规则表可测 |
---
## 8. 示例叙事(目标文档骨架)
````markdown
---
import:
la: ext/linalg/linalg.mq.md
---
# 转置反序
*`A` = > la.symbol name="A" rows=2 cols=3*
*`B` = > la.symbol name="B" rows=3 cols=2*
*`P` = `A` * `B`*
*`Pt` = > `P`.T*
叙述:\((AB)^\top = B^\top A^\top\)。
*`t` = > `Pt`.ascii*
1. `t` == "B^T*A^T"
> print text=identity-ok
2. *
> print text=identity-fail
````
计算面示例保持 `examples/linalg-least-squares/`(`lstsq` + heatmap),与代数面示例分目录或分章节。
---
## 9. 开放问题
1. **自动 simplify 是否改变 `ascii` 金样**——凡依赖「未化简乘积串」的测试需改期望或改调 `repr_raw`(若提供)。
2. **中文 `_type=矩阵` 与展示**——方法链已 retag;view 是否统一显示英文 kind。
3. **`$$` 符号方言**——若做,必须经 `from_formula` 扩展,禁止改核心高中 formula 语义。
---
## 10. 收束
`ext/linalg` 的北极星不是「功能最多的矩阵库」,而是:
> **让大学线性代数(及更深)以可运行公式文档的形式存在于 Marqdo;跑通即在规则集内正确;计算与作图是显式步骤,不淹没代数叙述。**