TwistedTorusND::BuildStrategy

地址适用于 libtpu-0.0.40-cp314 wheel 中的 libtpu.so。其他版本会有所不同。

摘要

TwistedTorusND::BuildStrategy (0x137d0c00) 是一个驱动器，它把已分类的 twisted slice 转换为 all-reduce emitter 所依赖的按颜色 ring neighbour/ordinal 表。它是 StrategyND::BuildStrategy 的 twisted-torus 覆写：它先构建任何 torus strategy 都会构建的同一个矩形 ND ring，然后用 twist fold 覆写 doubled-axis 边，使短轴上的两个长度为 K 的 ring 首尾相接成一个长度为 2K 的 ring，而每个长轴承载一个普通的 doubled ring。参考框架是按轴的 ring schedule，类似 LLVM 的 reduce-scatter lowering 会发出的形式；区别在于一个逻辑 ring 会被 dateline seam 重新穿接到两个物理轴上。

这个函数是在设置序言之上运行的严格 phase pipeline。序言（UpdateMinMaxDims → InitColorDimensions）在 TwistedTorusND 构造函数（0x137d0040，调用点 0x137d00df / 0x137d0115）中运行，而不在 BuildStrategy 自身函数体中运行；它把三个 torus extent 归约为 (K, 2K) 标量和两个轴计数字段，然后填充 color_dims[6][3] 排列表。随后 BuildStrategy 读取这些已经填好的字段（[obj+0x5f0]/[obj+0x5f8]/[obj+0x600]/[obj+0x608]/color_dims），而不是重新计算它们。Stage 1 为每个颜色和活动维度构建未展开的 base ND ring（ComputeOrdinal、Torus2DevicePhase0Neighbor / MeshStrideNPhasekNeighbor，通过 UpdateNeighborLocation 写入）。然后 Stage 2 运行按颜色、按 ring 维度的循环，其内层索引 p ∈ {0,1,2} 是 color_dims[c] 的 ring-dimension column；该列中存储的物理轴决定此 phase 的 seam 是 K→2K 还是 2K→K，并分发到四个 seam builder。

重新实现者必须从本页带走的唯一洞察是：phase 索引 p 字面上就是每个 seam builder 的第三个实参，同时也是进入 color_dims[c] 的列索引。fold 方向不是由 p 选择的，而是由 color_dims[c][p] 命名的是哪个物理轴（K-axis 或某个 2K-axis）选择的。p 只选择结果落入三个 RingLocation neighbour/ordinal 槽中的哪一个。本页负责 BuildStrategy driver、phase→column 映射、InitColorDimensions，以及四个 seam builder 的角色；它不重新推导 twist predicate（Twist Predicate 与 Orientation）、按形状的 coordinate fold（Shape Folds、GetReplicaPair3DOnTwistedTorus），或下游 2-phase replica-group 构建（2-Phase Replica-Group 构造）。

重新实现时，契约是：

• 序言。 UpdateMinMaxDims 设置 min_dim_size_/max_dim_size_ 和 num_min_dims_/num_max_dims_ 计数；InitColorDimensions 将 color_dims[6][3] 填充为模 NumNetworkDimensions 的循环排列（或 degraded remap）。
• 两阶段构建。 一个 base rectangular ND ring（复用自 StrategyND），随后按颜色 seam 覆写 doubled-axis 边。
• phase→column→fold 映射。 Phase p 是 color_dims[c] 的列 p；该列的轴类别（K vs 2K）选择 fold 方向；四个 seam builder 应用它。
• 两个形状分支。 num_max_dims_ == 1（K_K_2K：一个 2K 轴）与 num_max_dims_ != 1 + num_min_dims_ == 1（K_2K_2K：两个 2K 轴）走结构上不同的轴识别路径。

入口点	TwistedTorusND::BuildStrategy 0x137d0c00（~0x18c0 B，结束于下一个符号 0x137d24c0）
签名	(TwistedTorusND* this, const Target&, LloRegionBuilder*)
序言	由 ctor TwistedTorusND::TwistedTorusND 0x137d0040 运行（不是由 BuildStrategy 运行）：UpdateMinMaxDims 0x137d0260 · InitColorDimensions 0x137d0800
ND-ring gate	[obj+0xa8] == 1（ND ring vs 1-D ring；与基类 StrategyND 相同）
分类器字段	num_max_dims_ [obj+0x600]（qword idx 192）· num_min_dims_ [obj+0x608]（idx 193）
Base-ring 辅助函数	ComputeOrdinal 0x137c5300 · Torus2DevicePhase0Neighbor 0x137c57a0 · MeshStrideNPhasekNeighbor 0x137c5cc0
Seam 构建器	UpdateNeighborsKTo2K 0x137d24c0 · UpdateNeighbors2KToK 0x137d29c0 · UpdateOrdinal2K 0x137d2c60 · UpdateOrdinal2KToK 0x137d28c0
Phase 索引	p ∈ {0,1,2} — 第三个调用实参 == color_dims[c] 列
VLOG 锚点	all_reduce_strategies.cc:390 ("TorusPhasekNeighbor, stride: ") · :1916 ("color count: ")
置信度	HIGH — phase dispatch、四个 seam builder、双分支分类器和序言均已反编译验证，除非某行/说明另有标注

---

1. 入口点与 Phase 流水线

TwistedTorusND::TwistedTorusND  (ctor)   0x137d0040   ── runs the setup prologue BEFORE BuildStrategy
  ├─ UpdateMinMaxDims                    0x137d0260   ── @0x137d00df: K/2K scalars + num-K/num-2K counts  (§3 of overview)
  └─ InitColorDimensions                 0x137d0800   ── @0x137d0115: `color_dims[6][3]` cyclic fill / degraded remap
       └─ UseResilientAlgorithmTwistedTorus 0x1c894fc0   ── env[0x1116] + GetDegradedAxis != -1 gate
            └─ InitColorDimensionsDegraded  0x137c6580   ── (resilient tail) degraded [6][3] remap

TwistedTorusND::BuildStrategy            0x137d0c00   ── twisted-torus override of StrategyND::BuildStrategy
  │   (reads the prologue fields above; does not call the prologue itself)
  ├─ STAGE 1 — base ND ring  (0x137d0e62..0x137d13ad, per color × dim)
  │    ├─ StrategyND::ComputeOrdinal     0x137c5300   ── coord -> ring ordinal
  │    ├─ Torus2DevicePhase0Neighbor     0x137c57a0   ── +1/-1 neighbour, no-wrap fast path
  │    ├─ MeshStrideNPhasekNeighbor      0x137c5cc0   ── neighbour with inline ModuloRingSize fold
  │    └─ UpdateNeighborLocation         0x137c5fa0   ── deposit into CwCore/CounterCwCore buffers
  └─ STAGE 2 — per-color, per-phase seam  (0x137d168a..0x137d1c68)
       ├─ UpdateNeighborsKTo2K           0x137d24c0   ── K-axis column: K->2K neighbour seam
       ├─ UpdateOrdinal2KToK             0x137d28c0   ── K-axis column: inverse 2K->K ordinal fold
       ├─ UpdateNeighbors2KToK           0x137d29c0   ── 2K-axis column: 2K->K neighbour seam
       └─ UpdateOrdinal2K                0x137d2c60   ── 2K-axis column: 2K ordinal fold
```text

函数体（序言已由构造函数完成）先是一个 base-ring 循环，然后按 2K 轴计数（`num_max_dims_`）进入一个**双向分支**，落到两个几乎相同的 Stage-2 循环中：一个用于单 2K 轴形状（K_K_2K），另一个用于双 2K 轴形状（K_2K_2K）。两个 Stage-2 循环都以相同的 seam-builder 词汇遍历 colors × phases；它们只在轴识别 CHECK 以及有多少 phase 落入 `2K→K` 分支上不同。

> **注意 —** `BuildStrategy` **不**决定每一跳由哪些物理 ICI link 承载；它只产生*逻辑* neighbour ordinals。物理 link 分配是 routing 半边的工作（`TwistedTorusTopology`，[routing 概览](../routing/overview.md)）。停留在本页的重新实现者拥有的是一个知道 partner、但不知道 wire 的 ring schedule。

---

## 2. 序言 — UpdateMinMaxDims 与 InitColorDimensions

### 目的

序言由 `TwistedTorusND` 构造函数（`0x137d0040`）在 `0x137d00df`/`0x137d0115` 处运行，早于进入 `BuildStrategy`；它把 slice 归约为函数其余部分 keyed on 的四个数，并填充 color-dimension 排列表。`BuildStrategy` 只读地消费这些字段。`UpdateMinMaxDims` (`0x137d0260`) 在 [Twist Predicate 与 Orientation](twist-predicate-orientation.md) 中被记录为 shape gate，并在[章节概览](overview.md#3-the-shape-gate-and-the-shape-fold-catalog)中总结；这里仅重复 BuildStrategy 消费的字段。

### 它留给 BuildStrategy 的字段

| 字段 | 偏移 | qword idx | 含义 |
|---|---|---|---|
| `min_dim_size_` (`K`) | `[obj+0x5f8]` | 191 | 短轴大小 |
| `max_dim_size_` (`2K`) | `[obj+0x5f0]` | 190 | 长轴大小；`CHECK max == 2·min` |
| `num_max_dims_` | `[obj+0x600]` | 192 | 等于 `2K` 的轴数量（2K-count） |
| `num_min_dims_` | `[obj+0x608]` | 193 | 等于 `K` 的轴数量（K-count） |
| `NumNetworkDimensions` | `[obj+0x598]` | 179 | 健康 slice 上为 `3`，degraded 时为 `2` |
| `dim_sizes_[i]` | `[obj+0xb8..0xc8]` | 23/24/25 | 按轴 extent（加载顺序 `Y,X,Z`） |

分类器字段由向量化的 `vpcmpeqq` 计数产生（在 `UpdateMinMaxDims` 中反编译可见），并定义形状：`num_max_dims_ == 1` 是 K_K_2K（一个长轴），`num_max_dims_ == 2` 且 `num_min_dims_ == 1` 是 K_2K_2K（两个长轴）。BuildStrategy 的顶层 Stage-2 分支正是 keyed on 这两个字段。

### InitColorDimensions — `color_dims[6][3]` 填充

`InitColorDimensions` (`0x137d0800`) 填充 `[6][3]` 表，该表为每个 color row 和每个 ring-dimension column 命名该列的 ring 所 traverses 的**物理 torus 轴**。

```c
function InitColorDimensions(this, target):                 // 0x137d0800
    if UseResilientAlgorithmTwistedTorus(target, …):        // 0x1c894fc0 — env[0x1116] + GetDegradedAxis != -1
        this.NumColors = NumNetworkDimensions - 1            // [obj+0x8] = [obj+0x598] - 1
        return InitColorDimensionsDegraded(target, …)        // 0x137c6580 — tail: demote dead axis to inner column
    this.NumColors = NumNetworkDimensions                    // [obj+0x8] = [obj+0x598]
    VLOG(1) << "color count: " << NumColors                  // all_reduce_strategies.cc:1916
    // non-resilient fill: each color row is a rotation of {0,1,2}
    for color c in 0 .. up_to_6:
        for column d in 0 .. NumNetworkDimensions-1:         // n = [obj+0x598] = 3
            color_dims[c][d] = (c·stride + d) mod n          // [obj+0xd0 + c*0x18 + d*8]

反编译显示模 n 算术字面上是 1 % n、2 % n、……（按 NumNetworkDimensions 做 idiv/div），因此每个 color 的三列都是 {0,1,2} 的循环旋转。.rodata 注释 "twisted topology should have 3 pairs of colors" 确认了 6 行（3×2）color 结构。resilient 路径尾调用 base InitColorDimensionsDegraded (0x137c6580)，即 picker 和 degraded-axis 机制使用的同一个 [6][3] remap，它把 dead axis 降级到 inner ring column。

怪异点 — 循环排列正是按颜色 seam 保持均衡的原因。因为每个 color row 都是 {0,1,2} 的一个旋转，连续的 color 会把 K-axis（K_K_2K 的 seam-bearing axis）放在不同列中。因此 K→2K fold 会按 color 在物理轴之间轮转，分散 doubled-axis ICI 带宽，而不是让一个 link set 过载。若重新实现者用常量排列填充 color_dims，会得到正确但不均衡的 ring。

---

3. Stage 1 — Base ND Ring

目的

在任何 twist 之前，BuildStrategy 会构建普通的矩形 ND ring，也就是 StrategyND::BuildStrategy 产生的同一个 ring，这样 seam phase 才有完整的 neighbour 表可供覆写。从概念上说，这是“未展开”的 torus：每个轴都是由自身 N 个 chip 构成、由 wrap link 闭合的扁平 ring，没有 dateline。

Gate 与算法

构建由 base strategy 使用的同一个 [obj+0xa8] == 1 ND-ring-vs-1-D-ring gate 保护。循环按 color、按 active dimension 运行：

function BuildBaseRing(this):                          // 0x137d0e62..0x137d13ad
    for color c, for active dim d:
        coord = copy RingLocation coords               // [rbp-0x70] <- [rbp-0x40]
        ord   = StrategyND::ComputeOrdinal(this, coord, …)     // 0x137c5300
        if (coord | ring_size) needs no wrap:          // fast path: (or rax,r13) == 0
            fwd = Torus2DevicePhase0Neighbor(coord, …, +1)     // 0x137c57a0
            bwd = Torus2DevicePhase0Neighbor(coord, …, -1)
        else:                                          // wrap path
            VLOG(1) << "TorusPhasekNeighbor, stride: " << stride   // all_reduce_strategies.cc:390
            coord' = ModuloRingSize(coord)             // inline SltS32/SaddS32/Sselect + SgeS32/SsubS32/Sselect
            fwd = MeshStrideNPhasekNeighbor(coord', …, +1, 1)     // 0x137c5cc0
            bwd = MeshStrideNPhasekNeighbor(coord', …, -1, 1)
        UpdateNeighborLocation(this, &CwCore[c][d],        fwd, …)   // 0x137c5fa0, [obj+0x238+c*0x48+d*0x18]
        UpdateNeighborLocation(this, &CounterCwCore[c][d], bwd, …)   //            [obj+0x3e8+…]
```text

内联 `ModuloRingSize` fold（`SltS32(coord,0)+SaddS32+Sselect` 和 `SgeS32+SsubS32+Sselect`）会在 mesh-stride neighbour 查询前把坐标 wrap 到 `[0, ring_size)`；在 no-wrap fast path 上则直接使用 `Torus2DevicePhase0Neighbor` 的 `+1`/`-1` neighbours。forward（clockwise）和 backward（counter-clockwise）neighbours 都会写入按颜色的 neighbour buffer：`[obj+0x238 + color*0x48 + dim*0x18]`（CwCore）和 `[obj+0x3e8 + …]`（CounterCwCore）。随后 Stage-2 seam 会**覆写**这些 buffer 中的 doubled-axis 条目。

---

## 4. Stage 2 — 按 Color、按 Phase 的 Seam

### 目的

Stage 2 会重新穿接 ring，使短轴上的两个长度为 `K` 的 segment 首尾相接成单个长度为 `2K` 的 reduce-scatter ring，同时用 seam（`+K`-mod-`2K` jump）切断循环依赖。它通过逐 color、逐 phase 覆写 base ring 留下的 doubled-axis 条目来做到这一点。

### phase → column → fold-direction 映射

Stage-2 循环是 `for color c (count ≤6): for phase p in {0,1,2}`。内层索引 `p` **同时**是每个 seam builder 的第三个实参，也是进入 `color_dims[c]` 的列索引：

```c
function SeamOverwrite(this):                          // 0x137d168a..0x137d1c68
    for color c in 0 .. NumColors-1:                   // [obj+0x8], <= 6
        for phase p in 0,1,2:                          // p == color_dims column AND seam-builder arg
            axis = color_dims[c][p]                     // [r13 + p*8 - 0xe8] = [obj+0xd0 + c*0x18 + p*8]
            if axis == K_axis_index:                    // [rbp-0x38]
                // this phase folds K -> 2K: join the two length-K rings
                UpdateNeighborsKTo2K(this, c, p, …, cw[p], ccw[p], lrb)    // 0x137d24c0
                UpdateOrdinal2KToK  (this, c, p, axis, …, lrb)            // 0x137d28c0 (inverse ordinal)
            else:                                       // axis is a 2K-axis ([rbp-0x48] / [rbp-0x80])
                // this phase folds 2K -> K: ordinary doubled ring
                UpdateNeighbors2KToK(this, c, p, …, cw[p], ccw[p], lrb)    // 0x137d29c0
                UpdateOrdinal2K     (this, c, p, axis, …, lrb)            // 0x137d2c60 (phases 0,1 only)

从栈上传入的 neighbour-info 实参每个 phase 递增 +0x18（cw[0]/ccw[0] 位于 [rcx+0]/[r14+0]，cw[1]/ccw[1] 位于 +0x18，cw[2]/ccw[2] 位于 +0x30），也就是 color row 的三个 RingLocation neighbour 槽，每个 phase column 一个。

分发表如下，包含字节精确的调用点及其 edx phase 立即数：

Phase p	color_dims[c][p] 轴类别	Seam builders（调用点，edx 立即数 = p）
0	K-axis	UpdateNeighborsKTo2K @0x137d183e + UpdateOrdinal2KToK @0x137d1871
0	2K-axis	UpdateNeighbors2KToK @0x137d18b9 + UpdateOrdinal2K @0x137d1a24
1	K-axis	UpdateNeighborsKTo2K @0x137d19c0 + UpdateOrdinal2KToK @0x137d1a4e
1	2K-axis	UpdateNeighbors2KToK @0x137d1a9b + UpdateOrdinal2K @0x137d1ad9
2	K-axis	UpdateNeighborsKTo2K @0x137d1beb + UpdateOrdinal2KToK @0x137d1c19
2	2K-axis	UpdateNeighbors2KToK @0x137d1c63 (no UpdateOrdinal2K)

怪异点 — phase 2 没有 UpdateOrdinal2K 调用。UpdateOrdinal2K ordinal fold 只在 phases 0 和 1 上触发（@0x137d1a24 和 @0x137d1ad9）；phase-2 的 2K-axis 分支只更新 neighbour 表（UpdateNeighbors2KToK @0x137d1c63）。若重新实现者对所有三个 phase 对称调用 ordinal fold，会破坏第三个 ring 维度的 ordinal；第三维的 2K ordinal 是有意保留为 base-ring 值的。这一点已由反编译验证：不存在第三个 UpdateOrdinal2K 调用点；上表列出的 Stage-2 循环（num_max_dims_ != 1 / K_2K_2K 分支，0x137d168a..0x137d1c70）恰好发出十一个 seam 调用（三个 KTo2K、三个 Ordinal2KToK、三个 2KToK、两个 Ordinal2K）。

易错点 — fold 方向由该列的轴类别选择，不是由 phase 编号选择。Phase p 只是一个槽索引。同一个 phase p=0 会对某个 color（其列 0 持有 K-axis）执行 K→2K fold，而对另一个 color（其列 0 持有 2K-axis）执行 2K→K fold，因为 InitColorDimensions 旋转了排列。用 p 而不是 color_dims[c][p] 驱动 fold，是最可能出现的重新实现 bug。

两个形状分支

BuildStrategy splits the Stage-2 loop on the 2K-axis count at [obj+0x600] (num_max_dims_):

if (num_max_dims_ == 1):                                // K_K_2K — one 2K axis
    find min_dim_index  (the K axis)                     // CHECK "min_dim_index >= 0"
    find the single max_dim_index (the 2K axis)          // CHECK "max_dim_index >= 0",
                                                         //       "dim_sizes_[max_dim_index] == max_dim_size_"
    // each color's columns are a rotation of {K, K, 2K}: one K->2K seam phase
else:                                                    // K_2K_2K — two 2K axes
    CHECK num_min_dims_ == 1                              // "num_min_dims_ == 1"  (exactly one K axis)
    find min_dim_index  (the single K axis)              // CHECK "dim_sizes_[min_dim_index] == min_dim_size_"
    find both 2K-axis indices ([rbp-0x48], [rbp-0x80])   // CHECK "num_min_dims_ == num_dims_ - 1"
    // each color's columns are a rotation of {K, 2K, 2K}: one K->2K seam, two 2K->K seams
```text

CHECK 字符串 `"num_min_dims_ == 1"`（`@0x137d1...`，在反编译函数体中带行锚点）、`"dim_sizes_[min_dim_index] == min_dim_size_"`、`"dim_sizes_[max_dim_index] == max_dim_size_"`、`"min_dim_index >= 0"`、`"max_dim_index >= 0"` 和 `"num_min_dims_ == num_dims_ - 1"` 均已逐字反编译验证，并确认字段名 `num_min_dims_`/`num_max_dims_`/`min_dim_index`/`max_dim_index`/`dim_sizes_[]`/`min_dim_size_`/`max_dim_size_`。K_K_2K 分支对每个 color 恰好产生一个 `K→2K` seam phase（持有 `K` 的那一列）和两个 ordinary-ring phase；K_2K_2K 分支对每个 color 产生一个 `K→2K` seam phase 和两个 `2K→K` seam phase。

> **注意 —** `K_2K_NK` 形状（`n > 2`）永远不会到达这个分支：`UpdateMinMaxDims` 的 `max == 2·min` CHECK 会在任何不恰好为 `K` 或 `2K` 的轴上 fatal-error，因此 jellyfish collective 会让每个 twisted slice 通过 `num_max_dims_ ∈ {1,2}` 机制进行 fold。字面意义上的 `nK` 长轴只对 routing 侧的 `TwistedTorusTopology` 有意义。见 [Shape Folds](shape-folds.md)。

---

## 5. 四个 Seam Builders

每个 Stage-2 phase 会调用一个 neighbour seam，再加上（通常）一个 ordinal seam。neighbour seam 重写 ring step 落在哪个物理 chip 上；ordinal seam 重写该 chip 占据的 ring index。这里回顾字节级数学；完整 coordinate fold 见 [GetReplicaPair3DOnTwistedTorus](get-replica-pair-3d.md) 和 [Shape Folds](shape-folds.md)。

### UpdateNeighborsKTo2K — `0x137d24c0`（K-axis column，K→2K）

将两个长度为 `K` 的 ring 首尾相接成长度为 `2K` 的 ring。seam predicate 在 `K`-segment 的最后一个 chip 处触发，并沿长轴跳转 `+K`：

```c
function UpdateNeighborsKTo2K(this, color, phase, dim, …):   // 0x137d24c0
    seam = SeqS32(coord, K-1)                            // K-1 = [obj+0x5f8]-1; high end of a K-segment
           AND (Pimm(dir == 1) OR SeqS32([obj+0x180], dir-1))
    // per coordinate in the ring: fold the long axis by +K mod 2K, gated by seam
    wrapped = ModuloRingSize(SaddS32(coord_long, K), 2K) // 0x137c61a0 — modulus = [obj+0x5f0] (2K)
    folded  = Sselect(seam, wrapped, base_coord)
    fwd_chip = ToChipId(folded, …)                       // ToChipId 0x1d519cc0
    // forward neighbour (CwCore), then backward (CounterCwCore) via a second seam pass
    [obj + color*0x48 + dim*0x18 + 0x238] = fwd_chip      // overwrite base-ring CwCore entry
    [obj + color*0x48 + dim*0x18 + 0x3e8] = bwd_chip      //   and the CounterCwCore entry

UpdateOrdinal2KToK — 0x137d28c0（K-axis column，inverse ordinal）

将 2K ring ordinal 映射回 [0, K)，这是对 joined ring 位置重新编号的 inverse fold：

function UpdateOrdinal2KToK(this, color, phase, dim, …):  // 0x137d28c0
    in_lower = SltS32(coord, K)                          // K = [obj+0x5f8] (min_dim_size_)
    ordinal' = Sselect(in_lower, SmodU32(ordinal, K), SsubS32(ordinal, K/2))
    // else branch subtracts K/2 = [obj+0x5f8]/2, not K; slot [obj + color*0x18 + phase*8 + 0x1a8]
```text

### UpdateNeighbors2KToK — `0x137d29c0`（2K-axis column，2K→K）

应用到每个长轴上的对称 `2K→K` neighbour seam，即普通 doubled-ring neighbour，带有让长轴保持为干净 `2K` ring 的 fold（结构上是 `KTo2K` 的镜像）。

### UpdateOrdinal2K — `0x137d2c60`（2K-axis column，2K ordinal；仅 phases 0,1）

跨 seam fold 长轴 ordinal，并按方向缩放：

```c
function UpdateOrdinal2K(this, color, phase, dim, dir, …):  // 0x137d2c60
    at_or_past = SgeS32(coord, K)
    slot       = [obj + color*0x18 + phase*8 + 0x1a8]        // the per-color/per-phase ordinal slot
    ordinal'   = Sselect(at_or_past,
                         SmodU32(SaddS32(ord, dir·K), dir·2K),   // dir·K = imul [obj+0x5f8]; dir·2K = imul [obj+0x5f0]
                         ord)

ordinal 槽偏移 [obj + color*0x18 + phase*8 + 0x1a8] 使 phase 实参成为进入按颜色 ordinal row 的列选择器，与 p 在 Stage 1 中对 neighbour buffer 扮演的角色相同。

Seam builder 映射

构建器	地址	列类别	作用
UpdateNeighborsKTo2K	0x137d24c0	K-axis	K→2K neighbour seam（+K-mod-2K jump）
UpdateOrdinal2KToK	0x137d28c0	K-axis	inverse 2K→K ordinal fold
UpdateNeighbors2KToK	0x137d29c0	2K-axis	2K→K neighbour seam
UpdateOrdinal2K	0x137d2c60	2K-axis	2K ordinal fold（仅 phases 0,1）

---

6. 函数映射

函数	地址	作用
TwistedTorusND::BuildStrategy	0x137d0c00	driver：序言 + base ND ring + 按颜色 seam
TwistedTorusND::UpdateMinMaxDims	0x137d0260	序言：K/2K 标量 + 轴计数
TwistedTorusND::InitColorDimensions	0x137d0800	color_dims[6][3] 循环填充 / degraded remap
UseResilientAlgorithmTwistedTorus	0x1c894fc0	env[0x1116] + GetDegradedAxis != -1 resilient gate
BaseStrategyND::InitColorDimensionsDegraded	0x137c6580	degraded [6][3] remap（resilient tail）
StrategyND::ComputeOrdinal	0x137c5300	coord → ring ordinal（Stage 1）
BaseStrategyND::Torus2DevicePhase0Neighbor	0x137c57a0	+1/-1 neighbour，no-wrap fast path
BaseStrategyND::MeshStrideNPhasekNeighbor	0x137c5cc0	带内联 ModuloRingSize fold 的 neighbour
BaseStrategyND::UpdateNeighborLocation	0x137c5fa0	写入 Cw/CounterCw neighbour buffers
TwistedTorusND::UpdateNeighborsKTo2K	0x137d24c0	K→2K neighbour seam
TwistedTorusND::UpdateOrdinal2KToK	0x137d28c0	inverse 2K→K ordinal fold
TwistedTorusND::UpdateNeighbors2KToK	0x137d29c0	2K→K neighbour seam
TwistedTorusND::UpdateOrdinal2K	0x137d2c60	2K ordinal fold（phases 0,1）
ModuloRingSize	0x137c61a0	+K-mod-2K coordinate wrap
ToChipId	0x1d519cc0	folded coordinate → chip ID

---

7. 尚未解析的内容

• K_2K_2K 的 2K-second-index 解析。 区分第一个 2K-axis index（[rbp-0x48]）与第二个（[rbp-0x80]）的 cmov 链（0x137d15e1..0x137d165c）已追踪到其类别效果，但尚未归约为按形状闭合的公式，以说明哪个物理轴会成为“primary” 2K seam。LOW。见 Shape Folds。
• UpdateNeighbors2KToK 字节级数学。 已定位并确认它与 UpdateNeighborsKTo2K 对称，但 2K→K seam predicate 尚未逐指令转录。MEDIUM。
• 下游 phase split。 BuildStrategy 构建按颜色的 ring neighbour/ordinal 表；随后 2K ring 如何被划分为 Phase0 reduce-scatter 和 Phase1 all-gather replica groups，由 2-Phase Replica-Group 构造 负责。

---

交叉引用

• Twisted Torus — 章节地图 — 本页展开的 subsystem map 和 BuildStrategy phase 摘要
• Twist Predicate 与 Orientation — UpdateMinMaxDims 的 max == 2·min predicate 以及 Orientation/Polarity 维度映射
• Shape Folds — seam builders 实现的 K_K_2K / K_2K_2K / K_2K_NK coordinate-fold catalog
• GetReplicaPair3DOnTwistedTorus — +K-mod-2K coordinate fold 和 num_max_dims == 2 gate
• 2-Phase Replica-Group 构造 — 按颜色 ring 如何变成 Phase0 RS / Phase1 AG replica groups
• SelectNDStrategy — ND Collective-Algorithm Picker — 构造 TwistedTorusND 并调用 BuildStrategy 的 C-ii 分支
• Degraded Axis — 输入 UseResilientAlgorithmTwistedTorus 的 GetDegradedAxis 来源
• 返回索引