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

8.8 KiB
Raw Permalink Blame History

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 「跑通即正确」的精确定义

不是「任意高深定理自动证明」。
是在声明的能力边界内,下列任一成立则文档该段视为正确:

  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 中缀 / 方法)

*`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. 开放问题

  1. 自动 simplify 是否改变 ascii 金样——凡依赖「未化简乘积串」的测试需改期望或改调 repr_raw(若提供)。
  2. 中文 _type=矩阵 与展示——方法链已 retag;view 是否统一显示英文 kind。
  3. $$ 符号方言——若做,必须经 from_formula 扩展,禁止改核心高中 formula 语义。

10. 收束

ext/linalg 的北极星不是「功能最多的矩阵库」,而是:

让大学线性代数(及更深)以可运行公式文档的形式存在于 Marqdo;跑通即在规则集内正确;计算与作图是显式步骤,不淹没代数叙述。