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