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>
237 lines
8.8 KiB
Markdown
237 lines
8.8 KiB
Markdown
# `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;跑通即在规则集内正确;计算与作图是显式步骤,不淹没代数叙述。**
|