diff --git a/doc/design/ext-linalg.md b/doc/design/ext-linalg.md new file mode 100644 index 0000000..6f6180e --- /dev/null +++ b/doc/design/ext-linalg.md @@ -0,0 +1,340 @@ +# `ext/linalg` — 公式优先的线性代数扩展 + +| | | +|---|---| +| 状态 | **Draft · 待实现** | +| 日期 | 2026-09-07 | +| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) | +| 路线图 | [roadmap/ext-linalg.md](../roadmap/ext-linalg.md) | +| 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [view.md](view.md) · [ext-quantum-q7.md](ext-quantum-q7.md) | +| 安装(规划) | `marqdo ext add linalg`(`linalg` / `线性代数`) | + +--- + +## 0. 一句话 + +**经典线性代数以「矩阵公式」为一等公民**:抽象表达式可化简、可展示、可选求值;稠密数值与分解图走 ABI 插件——**不**并入 `lib/math`,**不**挂在 `ext/quantum` 作者面。 + +--- + +## 1. 目标与非目标 + +### 1.1 目标 + +1. **公式类扩展**:在现有标量 `formula` 之上,引入 **矩阵表达式(MatExpr)**——`MatrixSymbol`、乘加、转置、逆、迹、行列式、分块、Kronecker——默认**不展开**。 +2. **大规模优化**:形状检查 + 重写规则 + 惰性求值 + 分解对象复用(见 §5)。 +3. **易于展示**:KaTeX 公式卡、结构 SVG(SVD/QR/消元/特征)、数值热力图;CLI 可断言的 ASCII。 +4. **文档即实验**:GFM 表声明矩阵 / 步骤;`.mq.md` 可读可跑。 + +### 1.2 非目标(首版) + +| 不做 | 原因 | +|------|------| +| 塞进 `lib/math` | 高中标量范围已锁定;大学 LA 属官方 ext | +| 复用 `quantum.*` 作者 API | 领域混淆;量子 Q7 保持量子语义 | +| 完整 SymPy / Mathematica | 规则表可控子集即可 | +| 稀疏格式 / GPU / 分布式 | 超出文档语言定位 | +| 矩阵微积分闭式(Jacobian 积木) | 记入路线图远期 | +| 在 `ext/**` 调 `host_*` | 硬约束;数值走插件名 | + +--- + +## 2. 分层架构 + +```text +作者 .mq.md + │ import la:ext/linalg/linalg.mq.md + ▼ +L1 官方 ext(GFM + ## 包装,中英分文件) + │ plugin.load name=linalg + ▼ +plugins/linalg(ABI v2) + ├── matexpr:符号树构造 / 重写 / latex + ├── dense:稠密 f64(可选复数)运算与分解 + └── draw:结构 SVG / heatmap + │ + ▼(可选) +核心 Value::Formula 仅保留「数值矩阵字面量」现状; +符号 MatExpr 以 **map `_type=linalg_expr`**(或插件句柄)承载,避免撑爆高中 formula AST。 +``` + +### 2.1 为何 MatExpr 不直接塞进 `formula::Expr` + +| 方案 | 利 | 弊 | 决策 | +|------|----|----|------| +| 扩展 `formula::Expr` | 与 `$$` 一体 | 核心膨胀;高中/大学边界糊 | ❌ | +| 插件侧表达式 + L1 对象 | 核心干净;可独立发版 | 需稳定 `_type` 与 latex 桥 | ✅ **采用** | +| 仅 list-of-list 数值 | 简单 | 无法公式优化与符号展示 | ❌ 仅作 `explicit` 结果 | + +**既有** `formula::Expr::Matrix`(数值 `$$`)继续服务量子门 / 小例子;`ext/linalg` 通过 `la.matrix` / `la.from_formula` 吸收为稠密叶子。 + +### 2.2 与量子的边界 + +| | `ext/linalg` | `ext/quantum` Q7 | +|--|--------------|------------------| +| 域 | 经典实/复矩阵 | 态 / 密度 / Pauli | +| Kronecker | 经典 ⊗ | 复合量子系统 | +| 图 | SVD/QR/GE/heatmap | hinton/city/qsphere/… | +| 复用 | 插件**私有**可共享 Jacobi/SVD 代码 | 作者面 API **分离** | + +--- + +## 3. 运行时对象(锁定草案) + +全部经插件构造,L1 返回 **map**(`_type` 稳定,金样可断言): + +| `_type`(英) | 中文标签 | 字段(最小) | 含义 | +|---------------|----------|--------------|------| +| `linalg_expr` | `线性式` | `repr`(S-expr 或内部 id)、`shape`=`[m,n]` 或符号维、`latex`、`ascii` | 抽象矩阵公式 | +| `linalg_dense` | `稠密阵` | `rows`, `cols`, `data`(行主 list[list])、`dtype`=`real`\|`complex` | 显式数值 | +| `linalg_factor` | `分解` | `kind`=`lu`\|`qr`\|`svd`\|`eig`\|`chol`,因子字段,`latex`,可选 `svg` | 分解结果 | +| `linalg_svg` | — | `kind`, `svg` 文本 | 与 quantum_svg 同构展示约定 | +| `linalg_solve` | `求解` | `x`, `residual`, `method` | 线性系 / 最小二乘 | + +形状:`shape` 允许整数或符号维名(字符串 `"n"`);不相容 → 硬错误。 + +--- + +## 4. 作者面 API(英文 `ext/linalg/linalg.mq.md`) + +中文镜像:`ext/linalg/线性代数.mq.md`(`矩阵` / `化简` / `求值` / `绘图`…)。 + +### 4.1 构造 + +```markdown +# matrix + +## symbol + + `name` + + `rows` + + `cols` +# → linalg_expr MatrixSymbol + +## eye / zeros / ones / diag + + … + +## from_list + + `data` # list[list] 或 table + +## from_formula + + `formula` # 吸收 Value::Formula Matrix 字面量 + +## block + + `blocks` # 表或嵌套 list of expr +``` + +文档写法偏好: + +````markdown +`A` = > la.matrix.symbol name=A rows=n cols=n + +`b` = +$$ +\begin{pmatrix}1\\0\\0\end{pmatrix} +$$ + +*`b` = > la.matrix.from_formula formula=`b` * +```` + +### 4.2 公式代数(返回 `linalg_expr`,惰性) + +| 英文 | 中文 | 语义 | +|------|------|------| +| `mul` / `add` / `sub` | `乘` / `加` / `减` | 形状检查后建树 | +| `transpose` / `T` | `转置` | | +| `inv` | `逆` | 符号逆;不立即求数值 | +| `pow` | `幂` | 整数幂 | +| `trace` / `det` | `迹` / `行列式` | 可得到标量 expr 或数值 | +| `kron` | `克罗内克` | **禁止**默认 expand | +| `simplify` | `化简` | 应用 §5 规则集 | +| `collapse` | `分块化简` | 对标 `block_collapse` | +| `latex` / `ascii` | `乳胶` / `文本` | 展示字符串 | +| `shape` | `形状` | | + +链式风格(L1 对象方法,可选): + +```markdown +*`AtA` = > `A`.T * +*`AtA` = > la.mul a=`AtA` b=`A` * +*`s` = > la.simplify expr=`AtA` * +``` + +### 4.3 求值与分解(热路径 → 稠密) + +| 英文 | 说明 | +|------|------| +| `eval` / `explicit` | 符号树 + 绑定表 → `linalg_dense`;超维硬错误 | +| `factorize` | `kind=lu\|qr\|svd\|eig\|chol` → `linalg_factor` | +| `solve` | `A`,`b`;或 `factor` + `b` | +| `lstsq` | 最小二乘 | +| `rank` / `norm` / `cond` | 数值度量 | +| `matmul` | 稠密乘(已 explicit 时) | + +维数上限(草案,可配置): + +| 操作 | 默认上限 | +|------|----------| +| `explicit` 稠密元素总数 | \(n\cdot m \le 10^4\)(如 100×100) | +| SVD / eig 方阵边长 | \(\le 64\)(与 quantum 密度同级) | +| 结构 SVG(无元素) | 边长示意可达数百(只画框) | +| KaTeX 完整数字阵 | \(\le 8\times 8\);更大只出摘要 + 结构图 | + +### 4.4 展示 + +| 英文 | `kind` | 说明 | +|------|--------|------| +| `show` | — | 写入 view:优先 `latex` 公式卡 | +| `draw` | `structure` | 形状/分块矩形(drawmatrix 风格) | +| `draw` | `heatmap` / `hinton` | 数值幅度 | +| `draw` | `svd` / `qr` / `ge` / `eig` | 分解结构图(对标 LAFigureSpecs) | +| `draw` | `path`= | 可选落盘 SVG | + +`show` 应对符号式**始终可用**(无需 `eval`)。 + +### 4.5 最小可运行示例(设计验收叙事) + +````markdown +--- +import la:ext/linalg/linalg.mq.md +import table:lib/table.mq.md +--- + +# main + +*`A` = > la.matrix.symbol name=A rows=3 cols=3 * +*`x` = > la.matrix.symbol name=x rows=3 cols=1 * +*`b` = > la.mul a=`A` b=`x` * + +*`s` = > la.simplify expr=`b` * +> la.show expr=`s` + +`M` = +$$ +\begin{bmatrix}2&0\\0&3\end{bmatrix} +$$ + +*`M` = > la.matrix.from_formula formula=`M` * +*`f` = > la.factorize matrix=`M` kind=eig * +> la.draw factor=`f` kind=eig path=eig.svg +```` + +--- + +## 5. 公式重写与「大规模优化」(核心) + +### 5.1 原则 + +1. **构造便宜,展开昂贵**——乘加只分配节点。 +2. **形状是类型系统**——`(m×k)·(k×n)` 合法;否则错误指向调用点。 +3. **化简是规则不动点**——有限规则表,可测、可文档化。 +4. **expand 显式开启**——`expand=True` 才对 Kronecker / 多项式矩阵做爆炸性展开。 +5. **数值路径旁路符号**——已 `explicit` 的叶子用稠密核,不再走规则。 + +### 5.2 v1 规则集(最小够用) + +| ID | 规则 | 例 | +|----|------|-----| +| R1 | 单位元 | `I*A → A`,`A*I → A`,`A+0 → A` | +| R2 | 双逆 | `(A^{-1})^{-1} → A` | +| R3 | 转置反序 | `(AB)^\top → B^\top A^\top`,`(A^\top)^\top → A` | +| R4 | 逆转置 | `(A^{-1})^\top → (A^\top)^{-1}` | +| R5 | 结合扁平 | `MatMul` 链扁平化 | +| R6 | 分块塌缩 | 对标 `block_collapse`(乘/加在块级分配) | +| R7 | Kronecker 结合 | `(A⊗B)⊗C → A⊗B⊗C`;**不**展开成元素 | +| R8 | 标量提出 | `c*(A+B) → c*A+c*B`(可选;默认关以免树变宽) | + +### 5.3 数值侧优化 + +| 策略 | 说明 | +|------|------| +| `factorize` 一次 | 多 RHS `solve` 复用 | +| 小阵专用核 | 2×2 / 3×3 闭式逆 / det(教学友好、可对照公式) | +| 复杂度护栏 | 超限错误信息建议「保持符号 / 降维 / 分块」 | +| 禁止静默降精度 | 病态 `cond` 可警告(stderr 或结果字段) | + +--- + +## 6. 展示设计(效果) + +### 6.1 通道 + +| 通道 | 符号 MatExpr | 稠密 | 分解 | +|------|--------------|------|------| +| view Structure | KaTeX `latex` 卡 | 小阵 KaTeX;大阵摘要 | 公式 + 可选 SVG | +| view Execution plots | — | heatmap SVG | `kind=svd|…` SVG | +| CLI `print` | `ascii` | `[[…],…]` 或摘要 | `svd(U,S,V)` 摘要 | +| writeback | 可选记录 latex | 可选 | 可选 | + +### 6.2 LaTeX 约定 + +- 符号:`A`,`A^{\top}`,`A^{-1}`,`AB`,`A \otimes B` +- 数值小阵:`\begin{bmatrix}…\end{bmatrix}` +- 分块:`\begin{bmatrix} A & B \\ C & D \end{bmatrix}` +- 喂给既有 view:与 `formula-card` / KaTeX 同源路径(L1 `show` → `host_query("record_plot")` 或扩展「record_math」若已有;无则复用 writeback + plot 列表) + +### 6.3 结构 SVG(教学主视觉) + +对标 LAFigureSpecs / drawmatrix,**不**依赖 Matplotlib: + +| `kind` | 画什么 | +|--------|--------| +| `structure` | 矩形块 + 标签(零块灰色) | +| `svd` | \(U\Sigma V^{\top}\) 块布局 + 秩分隔 | +| `qr` | 瘦/胖 QR 示意 | +| `ge` | 消元后上三角高亮 | +| `eig` | \(A=PDP^{-1}\) 或谱列表 + 对角 | +| `heatmap` | 单元填色(实数蓝红;复数幅值) | + +主题:复用文档站浅色;可选 `theme=light|dark|bw`(与 quantum Q8 令牌对齐时可后置)。 + +--- + +## 7. L1 / 插件 / CLI 约定 + +1. **`ext/linalg/**` 禁止 `host_*`**;只调 `plugin.*` 注册名(如 `linalg_simplify`)。 +2. **中英分文件**,CATALOG 双 id:`linalg` / `线性代数`。 +3. **`marqdo ext add linalg`**:与 web/agent/quantum 相同——优先 Release 预编译 native zip。 +4. **金样**:离线、确定性;SVG 断言含关键子串或稳定 hash 前缀。 +5. **依赖**:插件内自研稠密核(或慎重引入单一 crate,如 `nalgebra`——**实现期再议**;设计默认「可自研小维 + 可选 crate」)。 + +--- + +## 8. 分期(摘要;细节见路线图) + +| 阶段 | 交付 | +|------|------| +| **L0** | CATALOG + ping + L1 `ensure_plugin` | +| **L1** | `matrix.symbol` / dense 构造 / `mul`·`T`·`inv` 树 + `simplify` R1–R5 + `latex`/`show` | +| **L2** | `explicit` / 小阵运算 / `solve` / `det`·`trace` 数值 | +| **L3** | 分块 + `collapse`;Kronecker 惰性 | +| **L4** | `factorize` LU/QR/SVD/eig + 结构 SVG | +| **L5** | heatmap/hinton;examples + public 文档 + skill 摘要 | +| **L6+** | 复数、lstsq、条件数、矩阵微积分(远期) | + +--- + +## 9. 验收标准(设计级) + +1. 符号式 `(AB)^\top` 经 `simplify` 得 `B^\top A^\top`,**不**产生稠密数据。 +2. 不相容形状在符号 `mul` 即失败。 +3. `$$` 数值阵 → `from_formula` → `factorize kind=eig` → view 含 SVG 或 latex。 +4. Kronecker 默认不 expand;显式 `expand` 受维数护栏。 +5. 中英 L1 金样各至少一条;`ext add linalg` 路径文档化。 +6. 与 `ext/quantum` 无作者面符号冲突。 + +--- + +## 10. 风险与开放问题 + +| 项 | 备注 | +|----|------| +| MatExpr 序列化 | 金样 / write:倾向可打印 S-expr 或稳定 latex+shape,避免不透明指针跨进程 | +| 与标量 `formula` 混运算 | v1:标量只作 `c*A` 系数;`det` 结果若符号则另型或降为 `formula` 文本 | +| nalgebra 等依赖 | 实现 L2 时评估二进制体积与 ABI 体积 | +| record_math vs plot | 若仅 SVG/KaTeX 字符串,可先复用 plot/writeback | + +--- + +## 11. 一句话(收束) + +**`ext/linalg` 让线性代数公式保持可优化的表达式,用规则与结构图服务文档阅读,用受控稠密核服务验算——公式优先,数值可选,展示分层。** diff --git a/doc/design/ext-quantum-q7.md b/doc/design/ext-quantum-q7.md index d0fc513..fe594a6 100644 --- a/doc/design/ext-quantum-q7.md +++ b/doc/design/ext-quantum-q7.md @@ -210,7 +210,7 @@ - >6 qubit 稠密 ρ 的谱 / Hinton(请用态向量 API) - Matplotlib / WebGL / 交互拖拽 - 量子线性系统算法(HHL)、QSVT 电路构造 -- 把线性代数并入 `lib/math` +- 把线性代数并入 `lib/math`(经典公式优先的 LA 见规划 [ext-linalg.md](ext-linalg.md),作者面与 quantum 分离) --- diff --git a/doc/design/stdlib-math.md b/doc/design/stdlib-math.md index 4077cc9..77ddf35 100644 --- a/doc/design/stdlib-math.md +++ b/doc/design/stdlib-math.md @@ -4,7 +4,7 @@ |---|---| | 状态 | **已实现(M1–M4)** | | 日期 | 2026-08-05 | -| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [view.md](view.md) | +| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [view.md](view.md) · 大学线性代数见规划 [ext-linalg.md](ext-linalg.md) | | 导入 | `lib/math.mq.md`(英)· `lib/数学.mq.md`(中) | | 范围 | **高中数学**(初等函数、导数、圆锥曲线、简单方程);非大学 CAS | @@ -92,7 +92,7 @@ $$ | 代入求值 | `subs` → `num` 或公式 | | 求解 | 一元一次 / 二次闭式;其它用数值求根并标明 | -**不做(本波):** 多元方程组、极限 ε-δ、级数、积分保证、矩阵、复数完备、任意证明。 +**不做(本波):** 多元方程组、极限 ε-δ、级数、积分保证、**大学线性代数**(符号矩阵表达式 / 分解 —— 见 [ext-linalg.md](ext-linalg.md))、复数完备、任意证明。数值小矩阵字面量可在 `$$` 中解析为 `formula::Matrix`,但符号 MatExpr 与分解不在 `lib/math`。 ### 3.2 作图(P) @@ -210,6 +210,7 @@ Interpreter.plots: Vec