GetReplicaPair3DOnTwistedTorus

本页所有地址均适用于 libtpu-0.0.40-cp314 wheel 中的 libtpu.so（build-id 89edbbe81c5b328a958fe628a9f2207d，构建 libtpu_lts_20260413_b_RC00）。其他版本会不同。.text VMA 等于文件偏移（基址 0xe63c000）；.rodata VMA 等于文件偏移（基址 0x84a0000）。所有地址都是 VMA。下面的每个符号和 .rodata 表都存在于完整符号二进制中，并已与 IDA 反编译交叉核对；五个路由表是逐字节精确的 .rodata 转储。

摘要

本页负责说明两个字节级机制：它们把抽象的 collective ring 步骤转换成具体芯片，并且分别转换成具体物理 ICI 链路：

xla::jellyfish::GetReplicaPair3DOnTwistedTorus（0x1c893400，group_utils.cc）—— 两个 replica-group 构造器都会调用的坐标折叠。给定 Phase0/Phase1 组的三个循环索引，以及 twisted-torus 形状标量 (2K, K, num_max_dims, orientation)，它计算 twisted 2K ring 在该步骤放置芯片的物理坐标 (cY, cX, cZ)，然后返回 map[cY][cX][cZ]，也就是来自 GetPhysicalToLogicalMapping3D 的 {core0, core1} megacore 逻辑设备对。每个双倍轴分支都由致命的 CHECK("num_max_dims == 2") 门控。
n-hop Mapper hop-offset 表，limited-ICI 路由消费者（DmaDestinationRoutingTableEntryMapper）读取它们，把 (src_chip, dst_chip) 对转换成物理 DMA 目标端口。kCaseHopsSignToOffsets（0xb8f0fb0，32 项单轴表，以 (routing_case, hop_len, sign) 为键做 std::lower_bound）处理一/二/四/八跳单轴情形；四个 y_routing/x_routing 对角表（0xb8f0e70–0xb8f0f70）处理双轴同时变化情形；GetHopLength（0x1fc59c80）把坐标 delta 归约到 {1,2,4,8} 跳阶梯。

调用此折叠的 3 层嵌套循环 replica-group 构造见 2 阶段 Replica-Group 构造；折叠分派所依据的 orientation/polarity 枚举见 Twist 谓词与 Orientation。本页负责折叠主体、num_max_dims == 2 前置条件，以及 hop-offset 表。

对于重新实现，其契约是：

纯函数，无分配。 GetReplicaPair3DOnTwistedTorus 以引用接收 [Y][X][Z] map，并以值接收形状标量和三个循环索引；它返回 pair<long,long>，且从不修改 map。每次叶子访问都有边界检查（越界时 BUG()）。
num_max_dims == 2 门控是致命的，不可恢复。 任何 orientation 分支在 num_max_dims ∉ {1, 2} 时都会以逐字 CHECK 字符串 "num_max_dims == 2" 调用 LogMessageFatal（group_utils.cc 第 1558 / 1571 / 1584 行）。这是 jellyfish 侧对同一个 K/2K 专有不变量的执行；上游 UpdateMinMaxDims 也会执行该不变量。
hop-offset 表是只读有序静态表。 kCaseHopsSignToOffsets 按 (routing_case, hop_len, sign) 排序，因此 Mapper 会对它做二分搜索；结果 port_offset 被折叠为 (port_offset + base) mod 8 得到物理端口。对角表按 [row][col] 直接索引，元素步幅为 4 字节。


折叠	`xla::jellyfish::GetReplicaPair3DOnTwistedTorus` `0x1c893400`（`group_utils.cc`）
返回	`pair<long,long>` = `map[cY][cX][cZ]`（`{core0, core1}` megacore 逻辑设备 ID）
Map 来源	`GetPhysicalToLogicalMapping3D` `0x1c88a280` — 见 2 阶段 Replica-Group 构造
前置条件	`CHECK("num_max_dims == 2")` — 双倍轴分支上 `num_max_dims ≠ 2` 时致命（`group_utils.cc:1558/1571/1584`）
单轴路由表	`kCaseHopsSignToOffsets` `0xb8f0fb0`（32 × 4 int32），`std::lower_bound` 键为 `(routing_case, hop_len, sign)`
对角路由表	`y_routing` `0xb8f0e70` · `y_routing_0` `0xb8f0f30` · `x_routing` `0xb8f0ef0` · `x_routing_0` `0xb8f0f70`
Hop 阶梯归约	`GetHopLength` `0x1fc59c80` → `{1,2,4,8}`（`viperlite_pod/utils.cc:105`）
Mapper 分派	`DmaDestinationRoutingTableEntryMapper::Map` `0x1fc584e0` — `RoutingScheme`：`2 ⇒` 双轴，`1 ⇒` n-hop，`0 ⇒` all-to-all（直接 `target_port = dst_chip`），否则致命
置信度	HIGH（折叠分派 + `num_max_dims == 2` CHECK 已由反编译验证；五张表均为逐字节精确 `.rodata` 转储；lower_bound 键构造 + mod-8 折叠 + 对角分派已由反编译验证），除非某行/标注另有说明

1. 折叠的用途

两个 twisted-torus replica-group 构造器（GetPhase0ReplicaGroups、GetPhase1ReplicaGroups）在 (i, j_or_m, k) 上执行 3 层嵌套循环，并且在每一步都必须回答：twisted 2K ring 在这里放置的是哪颗物理芯片，其上有哪些逻辑设备？ 这就是 GetReplicaPair3DOnTwistedTorus 的全部工作。它是 +K-mod-2K 日期线 twist 进入 replica-group 设备列表的唯一位置。

两个构造器的调用协议固定一致（在 GetReplicaPair3D 调用点 0x137d395d 和 0x137d4231 处的 push 顺序已由反编译验证）：

text

GetReplicaPair3DOnTwistedTorus(
    map,        // a1: const ref to the [Y][X][Z] vector<vector<vector<pair<long,long>>>>
    dims,       // a2: long* = &{Y, X, Z}  (the three physical axis extents)
    2K,         // a3: the long-axis (max) size, the "is-this-axis-the-2K-axis" sentinel
    K,          // a4: the short-axis (min) size, the modulus for the second K-segment
    num_max_dims, // a5: count of axes equal to 2K  (1 ⇒ K_K_2K, 2 ⇒ K_2K_2K) — CHECK'd == 2
    orientation,  // a6: which physical axis is the long axis / shard-phase selector (0,1,…)
    i,          // a7: outer loop index  (X-axis member, "i")
    j_or_m,     // a8: middle loop index (Y-axis member, "j" in Phase0 / "m" in Phase1)
    k)          // a9: inner loop index  (Z-axis member, "k")
  -> pair<long,long>   // {core0_logical_id, core1_logical_id}
```text

> **易错点 —** IDA 原型列出了 9 个尾随 `long` 参数；有意义的是四个形状标量 `(2K, K, num_max_dims, orientation)` 加三个循环索引 `(i, j_or_m, k)`。`dims` 指针 `a2` 被解引用为 `*a2 = Y`、`a2[1] = X`、`a2[2] = Z`；折叠把每个值与 `a3 (= 2K)` 比较，以决定*哪个*物理轴是长轴。循环变量到轴的约定 `Y↔j`、`X↔i`、`Z↔k` 与整个 collective 半边使用的约定相同（已从两个构造器调用点的参数顺序确认）。

该函数不了解 colors、phases 或 megacore mode；它是一个无状态几何映射。构造器提供循环索引并消费返回的 pair（`first` → core0 的组，`second` → core1 的组）。map 的叶子类型是 `GetPhysicalToLogicalMapping3D` 存入的 `{core0, core1}` pair，因此一次折叠调用会产出一颗物理芯片的 *两个* megacore core。

---

## 2. `num_max_dims == 2` 前置条件

折叠的最外层分派是基于 `a6`（orientation / 长轴选择器）的三路分支：`a6 == 1`、`a6 != 0`（剩余非零情形）以及 `a6 == 0`（fall-through）。**在这三个分支的每一个内部**，当切片是双倍轴（`K_2K_2K`）情形时，代码都会先断言 `a5 (num_max_dims) == 2`，再进入对角 seam 路径。如果 `a5` 既不是 `1`（单倍轴快速路径）也不是 `2`，该分支会致命报错：

```text
if ( a5 != 2 )
{
  absl::log_internal::MakeCheckOpString<long,long>(a5, 2, "num_max_dims == 2");
  // group_utils.cc line 1558 / 1571 / 1584 (one per orientation arm)
  LogMessageFatal(..., "platforms/xla/service/jellyfish/lowering/group_utils.cc", line, msg);
  Flush(); ~LogMessageFatal();   // process aborts
}

反编译中字符串 "num_max_dims == 2" 出现三次，每个 orientation 分支一次，源代码行号分别为 1558、1571 和 1584。这是对 TwistedTorusND::UpdateMinMaxDims（0x137d0260）已经通过 max_dim == 2·min_dim 和 num_min_dims + num_max_dims == num_dims CHECK 建立的不变量进行逐调用执行（见 Twisted Torus 概览 §3）。这种冗余是有意的：该折叠是 group_utils.cc 中的自由函数，可以独立于类访问，因此它重新检查，而不是信任对象字段。

`num_max_dims` (`a5`)	含义	折叠路径
`1`	单个双倍轴（`K_K_2K`）	闭式单 seam 折叠（§3）；不触发 `CHECK`
`2`	两个双倍轴（`K_2K_2K`）	对角 `(+K, +K)` seam 折叠（§3）；`CHECK` 通过
任何其他值	不是 twisted torus	致命 `CHECK("num_max_dims == 2")`

注意 — 前置条件作用于 num_max_dims（2K 轴的数量），而不是 orientation a6。orientation 选择哪个物理轴承载长 ring（把 *a2 / a2[1] / a2[2] 与 2K 比较）；num_max_dims 选择有多少轴被双倍化。K_2K_NK（n > 2）形状不会以 num_max_dims > 2 到达这里，因为 collective 半边会通过同一套 num_max_dims ∈ {1,2} 机制折叠它；字面 nK 只对 routing 侧 TwistedTorusTopology 有意义（见 overview §2 易错点）。

3. 坐标折叠

在分派以及必要的 num_max_dims == 2 检查之后，每个分支都会从循环索引计算三个物理坐标 (cY, cX, cZ)，并对切片中被双倍化的轴应用 +K-mod-2K seam。然后折叠返回 map[cY][cX][cZ]。

3.1 单个双倍轴 — `num_max_dims == 1`（`K_K_2K`）

这是闭式形式（逐字节精确来自 a6 == 0/a5 == 1 分支，行 0x1c8932xx 以及 fall-through 块 0x1c893560+）。令 j = a8 为 2K ring 成员索引，i = a7，k = a9，K = a4：

输出坐标	值	含义
`cY`	`(Y == 2K) ? j : (j mod K)`	如果 Y 是长轴，则为普通 `2K` ring；否则沿短 K 轴行走
`cX`	`((X == 2K && j ≥ K) ? K : 0) + i`	如果 X 是长轴，则第二个 K 段沿 X 偏移 `+K`
`cZ`	`((Z == 2K && j ≥ K) ? K : 0) + k`	如果 Z 是长轴，则第二个 K 段沿 Z 偏移 `+K`

其模式是：{Y, X, Z} 中恰好一个等于 2K（长轴）。ring 成员 j 取 0..2K-1。在长轴上，前 K 步（j < K）落在下半段，后 K 步（j ≥ K）跳 +K 到上半段，也就是日期线。在另外两个短轴上，坐标只是循环索引；但当长轴是 Y 时，它会直接穿过 j（cY = j），并把 j mod K 折叠到短轴位置上。这正是坐标空间中的 UpdateNeighborsKTo2K seam（双倍轴是两个在 +K 步连接的 K 段）。

text

ring member j:    0  1  …  K-1 |  K  K+1  …  2K-1
long-axis coord:  0  1  …  K-1 |  K  K+1  …  2K-1   (Y==2K: plain 2K ring)
                  ───── lower ──┼──────── upper ────
short-axis fold:  j mod K runs 0..K-1 then repeats; +K applied to the long axis only
```text

**示例**（`K = 4`，`2K = 8`，形状 `K, K, 2K` 且 `Z == 2K`，因此 `Y = X = 4`、`Z = 8`；固定 `i = 1`、`k = 2`）。`2K` ring 行走 `j = 0..7`：

| `j` | `cY = j mod K` | `cX = i = 1` | `cZ = ((Z==2K && j≥K)?K:0) + k` | 落点芯片 `(Y,X,Z)` |
|---|---|---|---|---|
| 0 | 0 | 1 | `0 + 2 = 2` | `(0,1,2)` |
| 1 | 1 | 1 | `0 + 2 = 2` | `(1,1,2)` |
| 2 | 2 | 1 | `0 + 2 = 2` | `(2,1,2)` |
| 3 | 3 | 1 | `0 + 2 = 2` | `(3,1,2)` |
| 4 | 0 | 1 | `4 + 2 = 6` | `(0,1,6)` |
| 5 | 1 | 1 | `4 + 2 = 6` | `(1,1,6)` |
| 6 | 2 | 1 | `4 + 2 = 6` | `(2,1,6)` |
| 7 | 3 | 1 | `4 + 2 = 6` | `(3,1,6)` |

该 ring 先在 `Z = 2` 处沿短 `Y` 轴行走一次（`j = 0..3`），然后**沿长 `Z` 轴跳 `+K = +4`** 到 `Z = 6`，再行走一次 `Y`（`j = 4..7`）。两个 `K` 段占据双倍 `Z` 轴的两个半区；seam（`j = K` 处的 `+K` 跳转）就是日期线。每个落点芯片的 `map[cY][cX][cZ]` pair 都把自己的 `{core0, core1}` 贡献给以 `k·R + i` 为键的 Phase0 组。

### 3.2 两个双倍轴 — `num_max_dims == 2`（`K_2K_2K`）

这里两个 `2K` 轴都承载一个 `K` 段，seam 是应用于被穿行轴的显式 `(coord + K) mod 2K` 折叠。反编译显示，每个 orientation 都会在双倍轴上计算形如 `(a4 + index) % a3`（即 `(K + member) mod 2K`）的模约简，例如 `a6 != 0`/`a5 == 2` 分支：

```text
// when both a2[1] (X) and a2[2] (Z) equal 2K (the dominant K_2K_2K orientation):
cX = ((X == 2K) ? base : … ) + (member folded (+K) mod 2K)
cZ = ((Z == 2K) ? base : … ) + (member folded (+K) mod 2K)
// modular reductions:  (a4 + a7) % a3   and   (a4 + a8) % a3   appear verbatim

真正的双轴 twist 是对角 (+K, +K)：两个 2K 轴各承载一个 K 段，成员行走会通过同一个 (coord + K) mod 2K seam 折叠两个双倍轴，从而在两个物理轴之间平衡双倍轴 ICI 带宽。每个 orientation 的闭式形式（三个 a6 分支各自对应哪个物理轴是短 K 轴）已追踪到其 seam 效果，但尚未化简成单一的逐 orientation 公式，见 §5。

3.3 表返回 — 带边界检查

所有分支都会汇合到相同的叶子访问（0x1c8938c5+）：

text

// v12 = cY, v14 = cX, v10 = cZ  (the three folded coords)
if ( cY >= map.size() )                      BUG();   // outer (Y) bound
row    = map[cY];                                       // vector<vector<pair>>
if ( cX >= row.size() )                      BUG();   // middle (X) bound
inner  = row[cX];                                       // vector<pair<long,long>>
if ( cZ >= inner.size() )                    BUG();   // inner (Z) bound
return inner[cZ];                                       // pair{core0, core1}
```text

`24 * v12` / `24 * v14` 步幅是 24 字节的 `std::vector` 控制块；`16 * v10` 步幅是 `sizeof(pair<long,long>)`。返回的 `pair.first` 是 `core0` 的逻辑设备 ID，`pair.second` 是 `core1` 的逻辑设备 ID，也就是构造器拆分到不同组中的 megacore pair。

> **易错点 —** 外层分派和接受 `CHECK` 的标量是**两个不同参数**。分派基于 `a6`（orientation / 长轴选择器）；`CHECK("num_max_dims == 2")` 基于 `a5`（`num_max_dims`，`2K` 轴数量）。`K_K_2K`（`a5 == 1`）快速路径从不触发 CHECK，只有两个双倍轴的分支会断言 `a5 == 2`。置信度：HIGH（三处 CHECK 字符串出现 + `a5 != 2` 分支）。

---

## 4. n-hop Mapper hop-offset 表

collective 知道自己与*谁*规约（上面的 replica groups）之后，路由生成器必须决定每个 `(src_chip, dst_chip)` 传输由*哪条物理 ICI 链路*承载。在 limited-ICI（n-hop）拓扑上，这个决策是 `DmaDestinationRoutingTableEntryMapper` 中的纯表查找，由 `Map`（`0x1fc584e0`）按 `RoutingScheme` 参数（`a5`，已在 `Map` 尾部由反编译验证）分派：`== 2 ⇒` `MapTwoAxesReachable`（对角），`== 1 ⇒` `MapOneTwoFourEightHopNeighborsReachable`（单轴 n-hop），`== 0 ⇒` all-to-all（路由的 `target_port` 直接设为目标芯片 ID，无表），其他值 ⇒ 致命 `"Unsupported routing scheme: %d"`。下面五张表都是逐字节精确的 `.rodata` 转储。

### 4.1 单轴表 — `kCaseHopsSignToOffsets`（`0xb8f0fb0`）

`MapOneTwoFourEightHopNeighborsReachable`（`0x1fc588a0`）处理源和目标只在**一个**轴上不同的情形。它构造 3 元组搜索键，并对 32 项有序表做 `std::lower_bound` 搜索（项步幅 16 字节 = 4 个 int32 `{routing_case, hop_len, sign, port_offset}`）。RetCheck 字符串逐字为：`"kCaseHopsSignToOffsets.contains( {routing_case, hop_len, hops > 0 ? POSITIVE : NEGATIVE})"`。

键的构造如下（反编译验证于 `0x1fc58b00`+）：

```text
routing_case = (coord_parity & 1) + (near ? 3 : 1)   // group 1..4
   // near = (the differing-axis hop count <= 4); coord_parity = source coord & 1
   // same-axis branch (v78 == v80): +3 if hop<=4 else +1; else (cross) +1
hop_len = GetHopLength(|delta|) in {1,2,4,8}          // 0x1fc59c80
sign    = (delta <= 0) + 1                            // 1 = POSITIVE (delta > 0), 2 = NEGATIVE (delta <= 0)

匹配项的 port_offset（第 4 个 int）被折叠为物理端口（0x1fc58c8e+）：

text

base        = dma_axis_term + axis_factor * stride   // v79 + v16 * v17 in the decompile
target_port = (port_offset + base) mod 8             // (x + 7) & ~7 trick for the floor
```text

`kCaseHopsSignToOffsets`（32 × 4 int32，逐字节精确；`routing_case ∈ 1..4`、`hop_len ∈ {1,2,4,8}`、`sign ∈ {1,2}`、`port_offset ∈ 0..7`）：

```text
idx  case hop sign -> off        idx  case hop sign -> off
[ 0]  1   1   1  ->  1           [16]  3   1   1  ->  4
[ 1]  1   1   2  ->  2           [17]  3   1   2  ->  2
[ 2]  1   2   1  ->  5           [18]  3   2   1  ->  5
[ 3]  1   2   2  ->  6           [19]  3   2   2  ->  1
[ 4]  1   4   1  ->  7           [20]  3   4   1  ->  7
[ 5]  1   4   2  ->  4           [21]  3   4   2  ->  6
[ 6]  1   8   1  ->  3           [22]  3   8   1  ->  3
[ 7]  1   8   2  ->  3           [23]  3   8   2  ->  3
[ 8]  2   1   1  ->  7           [24]  4   1   1  ->  7
[ 9]  2   1   2  ->  1           [25]  4   1   2  ->  5
[10]  2   2   1  ->  3           [26]  4   2   1  ->  4
[11]  2   2   2  ->  4           [27]  4   2   2  ->  0
[12]  2   4   1  ->  5           [28]  4   4   1  ->  1
[13]  2   4   2  ->  2           [29]  4   4   2  ->  6
[14]  2   8   1  ->  6           [30]  4   8   1  ->  2
[15]  2   8   2  ->  6           [31]  4   8   2  ->  2

注意 — 四个 routing_case 组编码不同轴的 (axis-class, coord-parity)；{1,2,4,8} 阶梯是 n-hop 生成器发出的可达性；sign 是 SerDes 方向（+/-）。"near vs far" 的几何含义（+3 与 +1 偏移）已追踪到 hop_len <= 4 分支，但尚未固定到具名物理轴身份，见 §5。

4.2 对角表 — `MapTwoAxesReachable`（`0x1fc58fa0`）

当源和目标在两个轴上同时不同时，Mapper 会读取四个直接索引表之一。分派依据是拓扑 X 维度 v53（一个 topology getter；在 0x1fc59102/0x1fc59107 处对它执行 cmp $0x4 / cmp $0x8），以及传输沿哪个轴运行（src.y == dst.y ⇒ Y 轴表；src.x == dst.x ⇒ X 轴表；二者都相等 ⇒ 同源/同目标错误）：

X-dim (`v53`)	Y 轴传输（`y == dst_y`）	X 轴传输（`x == dst_x`）	行索引	列索引
`8`	`y_routing` (4×8) `0xb8f0e70`	`x_routing` (16 int32) `0xb8f0ef0`	Y：`src_y / 2` · X：`src_x mod 2`	另一轴 hop
`4`	`y_routing_0` (2×8) `0xb8f0f30`	`x_routing_0` (4×4) `0xb8f0f70`	Y：`src_y / 2` · X：`src_x mod 4`	另一轴 hop

叶子访问（反编译验证于 0x1fc58fa0+）是在所选表中以字节偏移 4*col + row_stride*row 读取：

y_routing / y_routing_0（每行均为 8 个 int32）：偏移 4*col + 32*(src_y / 2)。
x_routing_0（v53 == 4，每行 4 个 int32）：偏移 4*col + 16*(src_x mod 4)，是真正的 4×4。
x_routing（v53 == 8）：偏移 4*col + 32*(src_x mod 2) 且 col < 8，这 16 个 int32 被按 2×8 块索引，不是下面 .rodata 转储打印出的 4×4。下面的转储行展示原始 16 个 int32 的存储顺序；v53 == 8 的 X 轴路径按 2×8 步幅行走它们。

无效 X-dim 或 same-axis 传输会报错："Two axes routing only supports slices of dimension X equal to 4 or 8"、"Two axes routing only supports transfers along X or Y axes"、"Mapper should not be called with same src/dst"（全部已由反编译验证）。

y_routing（4×8，0xb8f0e70）：

text

row0:  0  8  2 10  4 12  6 14
row1:  2 10  4 12  6 14  0  8
row2:  4 12  6 14  0  8  2 10
row3:  6 14  0  8  2 10  4 12
```text

`y_routing_0`（2×8，`0xb8f0f30`）：

```text
row0:  0  4  8 12  2  6 10 14
row1:  2  6 10 14  0  4  8 12

x_routing（4×4，0xb8f0ef0）：

text

row0:  9  1 11  3
row1: 13  5 15  7
row2:  1  9  3 11
row3:  5 13  7 15
```text

`x_routing_0`（4×4，`0xb8f0f70`）：

```text
row0:  5  1  7  3
row1:  1  5  3  7
row2: 13  9 15 11
row3:  9 13 11 15

值 0..15 是 4-bit 物理 ICI 目标端口编码，会直接存入 route_entry.target_port。_0 变体是小 pod（X-dim 4）拓扑版本。除了 X-dim == 4 vs 8 分派之外，每种 pod-size 适用哪个变体仍未解决，见 §5。

4.3 hop 阶梯归约 — `GetHopLength`（`0x1fc59c80`）

GetHopLength 是对有符号 delta 的 switch，会把 ±1/±2/±4/±8 归约到无符号 hop length {1,2,4,8} 并设置 StatusOr 成功标志；任何其他值都会在 viperlite_pod/utils.cc:105 返回 MakeErrorImpl<3>("Invalid hops: %d")：

输入 delta	hop_len	输入 delta	hop_len
`±8`	`8`	`±2`	`2`
`±4`	`4`	`±1`	`1`
任何其他值	error (`"Invalid hops: %d"`)

因此 n-hop 阶梯上的坐标 delta 总是四个 2 的幂可达步长之一；sign（SerDes 方向）由调用方另行恢复（delta <= 0）。

5. 尚未解决的问题

K_2K_2K 的逐 orientation 闭式形式。 §3.2 逐字节确认了 (+K) mod 2K seam 和主导（X = Z = 2K）orientation，但完整的逐 orientation case 表（三个 a6 分支中哪个物理轴是短 K 轴）只追踪到 seam 效果，尚未化简为一个闭式公式。MEDIUM。
routing_case 的 "near vs far" 轴类。 §4.1 确认了 routing_case = (parity & 1) + (near ? 3 : 1)，以及组 {1,2}/{3,4} 是 near/far 两半，但 "near vs far" 的确切物理含义（哪个轴类/环绕方向选择 +3 而不是 +1）只追踪到 hop_len <= 4 分支，尚未绑定到具名轴。MEDIUM。
y_routing 与 y_routing_0 的 pod-size 选择。 除 X-dim == 8 vs 4 分派之外，每种 pod 选择哪个变体是从分派立即数推断的，尚未绑定到具名 TpuChipConfig pod-size 字段。MEDIUM。
RoutingScheme 枚举值集合。 分派选择器已逐字节证明 0（all-to-all）、1（n-hop）、2（双轴），任何其他值都会命中 "Unsupported routing scheme: %d"；符号枚举器名称（哪种拼写映射到 0/1/2）尚未解码。LOW。
≥2-phase 折叠分支。 a6 == 1 orientation 分支是结构上独立的 seam，只有未来启用 >1-phase twisted sharding 时才会到达；GetPerColorShardIdTable 的 1-phase 门控使它在 v0.0.40 中不可达。其 collective 语义未被实际执行。LOW。见 2 阶段 Replica-Group 构造。

6. 函数与表映射

符号	地址	作用
`GetReplicaPair3DOnTwistedTorus`	`0x1c893400`	坐标折叠；返回 `map[cY][cX][cZ]` pair
`CHECK("num_max_dims == 2")`	`group_utils.cc:1558/1571/1584`	每个 orientation 的致命前置条件
`GetPhysicalToLogicalMapping3D`	`0x1c88a280`	构建 `[Y][X][Z] → {core0,core1}` map
`DmaDestinationRoutingTableEntryMapper::Map`	`0x1fc584e0`	`RoutingScheme` 分派（2 ⇒ 双轴，1 ⇒ n-hop，0 ⇒ all-to-all，否则致命）
`MapOneTwoFourEightHopNeighborsReachable`	`0x1fc588a0`	单轴 n-hop 查表 + mod-8 端口折叠
`MapTwoAxesReachable`	`0x1fc58fa0`	对角双轴查表
`GetHopLength`	`0x1fc59c80`	`±{1,2,4,8} → {1,2,4,8}` 归约（`utils.cc:105`）
`kCaseHopsSignToOffsets`	`0xb8f0fb0`	32 × 4 int32 单轴 `(case,hop,sign)→offset`
`y_routing`	`0xb8f0e70`	4 × 8 int32 对角端口表（X-dim 8）
`y_routing_0`	`0xb8f0f30`	2 × 8 int32 对角端口表（X-dim 4）
`x_routing`	`0xb8f0ef0`	4 × 4 int32 对角端口表（X-dim 8）
`x_routing_0`	`0xb8f0f70`	4 × 4 int32 对角端口表（X-dim 4）

交叉引用

Twist 算法（本节）

Twisted Torus — 章节地图 — 子系统地图；K/2K 形状门控与类族
2 阶段 Replica-Group 构造 — 调用此折叠的 Phase0/Phase1 3 层嵌套循环；GetPhysicalToLogicalMapping3D
Twist 谓词与 Orientation — 折叠分派所用的 orientation 枚举；max == 2·min 谓词
TwistedTorusND::BuildStrategy — 此折叠在坐标空间镜像的逐 color UpdateNeighborsKTo2K seam
Get Tiebreak — twisted slice 上 routing 侧的等距 tiebreak 规则

相邻章节

Get Static Path — 消费 per-link route table 的 routing 侧路径构造
Get Distances — 经 twist 调整的 torus-reduced distance vector
返回索引

GetReplicaPair3DOnTwistedTorus ​

摘要 ​

1. 折叠的用途 ​

3. 坐标折叠 ​

3.1 单个双倍轴 — num_max_dims == 1（K_K_2K） ​

3.3 表返回 — 带边界检查 ​

4.2 对角表 — MapTwoAxesReachable（0x1fc58fa0） ​

4.3 hop 阶梯归约 — GetHopLength（0x1fc59c80） ​

5. 尚未解决的问题 ​

6. 函数与表映射 ​

交叉引用 ​

Twist 算法（本节） ​

相邻章节 ​

GetReplicaPair3DOnTwistedTorus

摘要

1. 折叠的用途

3. 坐标折叠

3.1 单个双倍轴 — `num_max_dims == 1`（`K_K_2K`）

3.3 表返回 — 带边界检查

4.2 对角表 — `MapTwoAxesReachable`（`0x1fc58fa0`）

4.3 hop 阶梯归约 — `GetHopLength`（`0x1fc59c80`）

5. 尚未解决的问题

6. 函数与表映射

交叉引用

Twist 算法（本节）

相邻章节