📝 docs(tsl): restructure agent-facing reference
Rework TSL syntax, catalog, modules, and routing docs around deterministic agent lookup and generation. Split large catalog pages into focused function fact pages, remove obsolete pending/verified/unavailable paths, and update consistency tests for the new structure.
This commit is contained in:
@@ -0,0 +1,232 @@
|
||||
# TSL 矩阵深水专题
|
||||
|
||||
文档类型：语法深水专题
|
||||
是否可直接用于生成代码：是
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[12_matrix_and_collections.md](12_matrix_and_collections.md)、[23_fmarray.md](23_fmarray.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
|
||||
这一篇只讲矩阵专用语法主干：矩阵初始化、数列构造、矩阵逆/广义逆，以及怎样读取矩阵的行列大小和索引。它和 [12_matrix_and_collections.md](12_matrix_and_collections.md) 的分工是：`13` 只讲数组与矩阵样数据，这一篇讲矩阵专用构造、运算与大小接口。
|
||||
|
||||
## 本篇职责
|
||||
|
||||
回答“怎样直接构造全零矩阵、全一矩阵、随机矩阵、单位矩阵、空矩阵和数列数组，怎样写矩阵逆/广义逆，以及怎样拿到矩阵的行数、列数、行索引和列索引”。
|
||||
|
||||
## 智能体矩阵深水判断流程
|
||||
|
||||
1. 先判断要写矩阵初始化、数列构造、矩阵逆/广义逆，还是矩阵尺寸与索引读取。
|
||||
2. 基础数组和矩阵样比较先回看 `12_matrix_and_collections.md`。
|
||||
3. `mrows` / `mcols` / `msize` 等函数只照文档返回形态写。
|
||||
4. 不要把列索引数组误当成单个数字。
|
||||
5. 没有对应代码块时不要发明矩阵深水写法。
|
||||
|
||||
## 核心规则
|
||||
|
||||
- 矩阵初始化函数的参数规格见 [../reference/catalog/math.md](../reference/catalog/math.md)；本页只保留矩阵行为示例和返回形态边界。
|
||||
- `zeros(...)`、`ones(...)`、`rand(...)`、`nils(...)`、`eye(...)` 都可以直接用于矩阵初始化。
|
||||
- `zeros(3)`、`ones(3)`、`nils(2)` 这类单参数写法可以直接生成一维结果。
|
||||
- `zeros(2, 3)`、`rand(2, 3)` 这类双参数写法可以直接生成二维矩阵。
|
||||
- `zeros(2, array("A", "B"))` 这种写法可以直接生成带列名的二维结果。
|
||||
- `eye(3)` 生成的是 `3 x 3` 单位矩阵，不是一维数组。
|
||||
- `->` 用来生成数列；默认步长是 `1`，也可以显式传入步长和索引数组。
|
||||
- 在矩阵语境里，`!A` 是一元倒数运算符作用于矩阵的形态，用于矩阵逆/广义逆；非方阵输入可以返回行列数互换后的广义逆结果。
|
||||
- `msize(...)`、`mrows(...)`、`mcols(...)` 的参数规格见 [../reference/catalog/system.md](../reference/catalog/system.md)。
|
||||
- `msize(matrix_value)` 返回 `array(行数, 列数)`。
|
||||
- `msize(matrix_value, 1)` 返回行索引数组和列索引数组。
|
||||
- `mrows(matrix_value)` / `mcols(matrix_value)` 默认返回数量；第二个参数写成 `1` 时返回索引数组。
|
||||
- `mrows(matrix_value, 1)` / `mcols(matrix_value, 1)` 的返回值可用于索引匹配；不要把它们当成数量。
|
||||
|
||||
## 可直接照写示例
|
||||
|
||||
### 矩阵初始化
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
zeros_1d := zeros(3);
|
||||
zeros_2d := zeros(2, 3);
|
||||
ones_1d := ones(3);
|
||||
nils_1d := nils(2);
|
||||
eye_2d := eye(3);
|
||||
rand_2d := rand(2, 3);
|
||||
named_zeros := zeros(2, array("A", "B"));
|
||||
writeLn(length(zeros_1d));
|
||||
writeLn(mrows(zeros_2d));
|
||||
writeLn(mcols(zeros_2d));
|
||||
```
|
||||
|
||||
结果说明：
|
||||
|
||||
- `zeros(3)` 的长度是 `3`，前三个元素依次是 `0`、`0`、`0`
|
||||
- `zeros(2, 3)` 的行数是 `2`、列数是 `3`，第一行前三个元素是 `0`、`0`、`0`
|
||||
- `ones(3)` 的前三个元素依次是 `1`、`1`、`1`
|
||||
- `nils(2)` 可直接生成长度为 `2` 的结果
|
||||
- `eye(3)` 的行数是 `3`、列数是 `3`，并且 `(0,0)`、`(1,1)`、`(2,2)` 为 `1`，`(0,1)`、`(1,0)` 为 `0`
|
||||
- `rand(2, 3)` 的行数是 `2`、列数是 `3`
|
||||
- `zeros(2, array("A", "B"))` 的行数是 `2`、列数是 `2`，并且 `named_zeros[0]["A"]`、`named_zeros[0]["B"]`、`named_zeros[1]["A"]`、`named_zeros[1]["B"]` 都是 `0`
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
3
|
||||
2
|
||||
3
|
||||
```
|
||||
|
||||
### `->` 数列数组初始化
|
||||
|
||||
默认步长为 `1`：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
seq_default := 1 -> 5;
|
||||
```
|
||||
|
||||
结果说明：
|
||||
|
||||
- `seq_default` 是 `array(1, 2, 3, 4, 5)`
|
||||
|
||||
显式指定步长：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
seq_step := array(2.5, 0.5) -> 5;
|
||||
```
|
||||
|
||||
结果说明：
|
||||
|
||||
- `seq_step` 的长度是 `6`
|
||||
- 六个元素依次是 `2.5`、`3`、`3.5`、`4`、`4.5`、`5`
|
||||
|
||||
显式指定索引数组：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
seq_indexed := array(0, 1, array("A", "B", "C", "D", "E", "F")) -> 5;
|
||||
```
|
||||
|
||||
结果说明：
|
||||
|
||||
- `seq_indexed` 的长度是 `6`
|
||||
- `seq_indexed["A"]` 到 `seq_indexed["F"]` 依次是 `0`、`1`、`2`、`3`、`4`、`5`
|
||||
|
||||
### 矩阵一元倒数 / 逆 / 广义逆：`!A`
|
||||
|
||||
方阵输入返回普通矩阵逆：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
matrix_value := array((1, 2), (3, 4));
|
||||
inverse_value := !matrix_value;
|
||||
writeLn(mrows(inverse_value));
|
||||
writeLn(mcols(inverse_value));
|
||||
writeLn(inverse_value[0][0]);
|
||||
writeLn(inverse_value[0][1]);
|
||||
writeLn(inverse_value[1][0]);
|
||||
writeLn(inverse_value[1][1]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
2
|
||||
2
|
||||
-2
|
||||
1
|
||||
1.5
|
||||
-0.5
|
||||
```
|
||||
|
||||
非方阵输入返回广义逆：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
matrix_value := array((1, 2, 3), (4, 5, 6));
|
||||
inverse_value := !matrix_value;
|
||||
writeLn(mrows(inverse_value));
|
||||
writeLn(mcols(inverse_value));
|
||||
writeLn(inverse_value[0][0]);
|
||||
writeLn(inverse_value[0][1]);
|
||||
writeLn(inverse_value[1][0]);
|
||||
writeLn(inverse_value[1][1]);
|
||||
writeLn(inverse_value[2][0]);
|
||||
writeLn(inverse_value[2][1]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
3
|
||||
2
|
||||
-0.944444444444444
|
||||
0.444444444444444
|
||||
-0.111111111111111
|
||||
0.111111111111111
|
||||
0.722222222222222
|
||||
-0.222222222222222
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `array((1, 2, 3), (4, 5, 6))` 是 `2 x 3` 矩阵样数组。
|
||||
- `!matrix_value` 返回的是 `3 x 2` 广义逆结果。
|
||||
- 生成矩阵逆/广义逆时写 `!matrix_value`；不要把它改写成 `1 / matrix_value`。
|
||||
- `!` 不表示逻辑非；逻辑非回 [06_expressions_and_operators.md](06_expressions_and_operators.md) 使用 `not`。
|
||||
|
||||
### `msize`、`mrows`、`mcols`
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
matrix_rows := array(
|
||||
("A": 1, "B": 2),
|
||||
("A": 11, "B": 22),
|
||||
("A": 21, "B": 32)
|
||||
);
|
||||
size_info := msize(matrix_rows);
|
||||
size_index := msize(matrix_rows, 1);
|
||||
row_count := mrows(matrix_rows);
|
||||
row_index := mrows(matrix_rows, 1);
|
||||
col_count := mcols(matrix_rows);
|
||||
col_index := mcols(matrix_rows, 1);
|
||||
```
|
||||
|
||||
结果说明：
|
||||
|
||||
- `msize(matrix_rows)` 返回 `array(3, 2)`
|
||||
- `msize(matrix_rows, 1)` 的第一项是 `array(0, 1, 2)`，第二项是 `array("A", "B")`
|
||||
- `mrows(matrix_rows)` 返回 `3`
|
||||
- `mrows(matrix_rows, 1)` 返回 `array(0, 1, 2)`
|
||||
- `mcols(matrix_rows)` 返回 `2`
|
||||
- `mcols(matrix_rows, 1)` 返回 `array("A", "B")`
|
||||
|
||||
## 默认生成模板
|
||||
|
||||
需要矩阵构造时，优先从这个最短模板开始：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
matrix_value := zeros(2, 3);
|
||||
```
|
||||
|
||||
## 决策边界和禁止项
|
||||
|
||||
- 把 `eye(3)` 当成一维数组。
|
||||
- 把 `!A` 当成逻辑非表达式。
|
||||
- 以为 `mrows(matrix_value, 1)` 和 `mcols(matrix_value, 1)` 返回的还是数量。
|
||||
- 写带步长的 `->` 时，漏掉外层 `array(...)`。
|
||||
- 还在普通数组页里硬塞矩阵专用大小接口。
|
||||
|
||||
代码块身份：反例 / 不可照写
|
||||
|
||||
```text
|
||||
seq_value := 2.5, 0.5 -> 5;
|
||||
```
|
||||
|
||||
上面这种写法不对。显式步长模式需要写成 `array(2.5, 0.5) -> 5`。
|
||||
Reference in New Issue
Block a user