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>
8.8 KiB
8.8 KiB
ext/linalg — 公式文档面(跑通即正确)
| 状态 | Draft · 锁定作者面哲学与分期 |
| 日期 | 2026-09-07 |
| 父设计 | ext-linalg.md |
| 路线图 | roadmap/ext-linalg.md |
| 调研 | research/ext-linalg-formula.md |
| 对照 | stdlib-math.md(高中标量公式) |
0. 一句话
.mq.md 里的线性代数应当读起来像一份可运行的公式讲义:式子能跑通,就在库承诺的规则与维数下代表正确;lib/math 守高中边界,大学符号矩阵与更深层计算由 ext/linalg 正当承担。
1. 产品哲学
1.1 与 Marqdo 总原则对齐
| Marqdo | 在线性代数上的含义 |
|---|---|
| 代码即文档 | 矩阵代数段落用数学式书写,而不是 API 调用清单 |
| 标记即语法 | $$、中缀、# matrix 方法都是可读标记,不是「库胶水」 |
| 跑通可验收 | 金样 / 课堂作业:文件 exit 0 + 断言化简结果 = 式子合法 |
1.2 「跑通即正确」的精确定义
不是「任意高深定理自动证明」。
是在声明的能力边界内,下列任一成立则文档该段视为正确:
- 形状层:不相容维数的乘加在构造时硬错误(写不出可运行的坏式)。
- 恒等式层:文档断言的规范形(如
(AB)^\top → B^\top A^\top)经规则集得到。 - 数值核对层(可选):小
$$数值阵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 中缀 / 方法)
*`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 目标形态(文档感更强;分期实现)
叙事理想(不必一次做完):
# 正规方程
令 \(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 验收句式(金样)
*`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. 示例叙事(目标文档骨架)
---
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. 开放问题
- 自动 simplify 是否改变
ascii金样——凡依赖「未化简乘积串」的测试需改期望或改调repr_raw(若提供)。 - 中文
_type=矩阵与展示——方法链已 retag;view 是否统一显示英文 kind。 $$符号方言——若做,必须经from_formula扩展,禁止改核心高中 formula 语义。
10. 收束
ext/linalg 的北极星不是「功能最多的矩阵库」,而是:
让大学线性代数(及更深)以可运行公式文档的形式存在于 Marqdo;跑通即在规则集内正确;计算与作图是显式步骤,不淹没代数叙述。