Twisted Torus - 章节地图

本页中的所有地址都适用于来自 libtpu-0.0.40-cp314 wheel 的 libtpu.so（build-id 89edbbe81c5b328a958fe628a9f2207d，构建 libtpu_lts_20260413_b_RC00）。其他版本会不同。.text VMA 等于文件偏移（基址 0xe63c000）；所有地址都是 VMA。下列每个符号都存在于完整符号二进制中，并已与 IDA 反编译交叉核对。

摘要

本页是 twisted-torus 子系统的地图 - 当一个 ICI torus 轴恰好是短轴长度的两倍，而在该 doubled 轴上使用普通矩形 ring 会死锁时，libtpu 使用的几何结构。twisted torus 用一个 dateline twist 把 doubled（2K）轴折回到自身：collective 不是在一个物理轴上走 2K 个芯片的平直 ring，而是先走短 K 轴，沿长轴跳 +K，再第二次走 K 轴 - 因此 2K ring 被拆成两个 K 段，分别位于 doubled 维度的两半。twist（+K-mod-2K seam）打破了 folded torus 原本会携带的循环依赖，作用类似 dateline 在一维双向 ring 上提供的技巧。

该子系统有两个结构上不同、重实现者必须分清的半边，因为它们位于不同命名空间并回答不同问题：

collective-strategy 半边 - xla::jellyfish::TwistedTorusND - 为 twisted slice 构建逐 color 的 reduce-scatter / all-gather ring schedule 和 HLO ReplicaGroup 设备列表。它是 collective-algorithm picker 的消费者：当 picker 的 C-ii 分支检测到 twisted shape 时，它构造一个 TwistedTorusND。这一半拥有 BuildStrategy、K/2K shape classifier、四个 seam builder、两阶段 replica-group 构建，以及 megacore 偶/奇拆分。
routing 半边 - accel_ssw::deepsea::slice_builder::TwistedTorusTopology - 回答“在 twisted slice 上给定 (src, dst)，走哪些 link hop”以生成静态 route table。它拥有 InitRouteSolution、GetStaticPath、GetDistance，以及 k*k*2k/k*2k*2k route cache 所依据的 GetTiebreak 规则。它作为 routing section 的同级内容记录；本页定位它，但不重复其推导。

本页记录：(a) twisted torus 是什么以及支撑它的 dateline twist；(b) TwistedTorusND 类族及各成员位置；(c) BuildStrategy 阶段顺序 - 如何先构建逐 color ring，再由 seam phases 覆写 K/2K 轴 neighbour；(d) shape-fold 目录（K_K_2K / K_2K_2K / K_2K_NK）和 megacore 偶/奇拆分。每个算法都有自己的 twist 页面；本页链接它们，并不重新推导字节级数学。

对于重实现，该子系统的契约是：

Shape gate。 只有当 max_dim == 2*min_dim 且每个轴都是短 K 或长 2K 时，slice 才是 twisted（UpdateMinMaxDims 以 fatal CHECK 强制两者）。(num-2K-axes, num-K-axes) 计数把 slice 分类为三个 TwistedTorusShape enum 值之一。
类拆分。 TwistedTorusND（jellyfish，collective emission）与 TwistedTorusTopology（slice_builder，route table）是在不同命名空间中的独立类型；两者描述同一物理 twist，但产出不同 artifact。
Seam。 +K-mod-2K fold（UpdateNeighborsKTo2K 及相关函数）按 color、按 ring-dimension phase 应用于 doubled 轴（K_K_2K 中为一个轴，K_2K_2K 中为两个轴的对角线）。
两阶段 collective。 twisted all-reduce 是 Phase0 沿 2K ring 的 reduce-scatter，然后 Phase1 在正交 KxR 平面上的 all-gather - 仅支持 single-shard。


Collective-strategy 类	`xla::jellyfish::TwistedTorusND`（ctor `0x137d0040`，vtable `0x219242a0`）
Routing 侧类	`accel_ssw::deepsea::slice_builder::TwistedTorusTopology`（`InitRouteSolution` `0x20b3f7c0`）
SparseCore 变体	`xla::tpu::sparse_core::collective::TwistedTorusTopologyInfo`（`0x133e1980`）
Picker 入口（构造它）	`BaseStrategyND::SelectNDStrategy` C-ii 分支 - picker 页面
Twist 谓词	`max_dim == 2*min_dim`（`UpdateMinMaxDims` `0x137d0260`，`CHECK_EQ` `0x137d037a`）
Shape enum	`TwistedTorusShape {UNSPECIFIED, K_K_2K, K_2K_2K, K_2K_NK}`
BuildStrategy	`TwistedTorusND::BuildStrategy` `0x137d0c00`（base ND ring + 3 seam phases）
2-phase collective	`GetPhase0ReplicaGroups` `0x137d3560`（沿 2K 的 RS）* `GetPhase1ReplicaGroups` `0x137d3de0`（平面上的 AG）
坐标折叠	`GetReplicaPair3DOnTwistedTorus` `0x1c893400`（`+K`-mod-`2K` seam）
置信度	高（类族、`UpdateMinMaxDims` CHECK 字符串、`BuildStrategy` phase dispatch、`num_max_dims == 2` CHECK、shape 字符串均经反编译验证），除非某行/callout 另有说明

1. 什么是 twisted torus

3-D ICI slice 是一个芯片矩形网格，每个轴上都有 wrap-around link（torus）。Collective 以逐轴 ring 的形式使用该 torus：reduce-scatter 把每个芯片的 partial 发送给它的 ring neighbour，并沿环累积。在矩形 torus 上，每个轴的 ring 就是该轴上的 N 个芯片按顺序排列，并由 wrap link 闭合。

twist 解决的问题出现在某个轴的范围为 2K，而其他轴范围为 K 时（K = min，2K = max）。长轴上的自然 2K-chip ring 是一个 folded loop：它沿长轴向前穿过，wrap link 把它折回；在某些 slice shape 上，该 loop 的前进半边和返回半边会以形成循环 buffer-dependency 的方式竞争相同物理 link - 即 routing deadlock。这是 torus 版本的经典问题：没有 dateline 的单向 ring 会死锁。

twisted torus 通过重新穿线 2K ring 打破循环，使它的两半位于不同的物理 link 集上。具体来说（K_K_2K 情况，GetReplicaPair3DOnTwistedTorus num2K==1 fold）：

text

ring member index j = 0 .. 2K-1   (the 2K reduce-scatter ring)
   coord(K-axis)   =  j mod K              ── walk the short K-axis
   coord(2K-axis)  = (j >= K ? K : 0) + …  ── second pass offset by +K on the long axis
```text

该 ring 先走一次短 `K` 轴（`j = 0..K-1`），然后**沿长轴跳 `+K`**，再第二次走 `K` 轴（`j = K..2K-1`）。两个 `K` 段占据 doubled 维度的两半，因此 seam（`+K` 跳转，按 `2K` 取模）就是 dateline：循环依赖在每个 ring 上恰好被切开一个点。对于 `K_2K_2K` 情况，seam 同时应用于**两个** doubled 轴 - 对角线 `(+K,+K)` 偏移 - 因而两个 `2K` 轴各承载一个 `K` 段，doubled-axis ICI 带宽在两者之间平衡。seam 数学见 [Twist Predicate & Orientation](twist-predicate-orientation.md)，逐 color 应用见 [BuildStrategy](buildstrategy.md)。

> **说明 -** twist 是*逻辑 ring layout* 的属性，不是硬件属性：使用的是同一个物理 3-D torus。twist 改变的是每个 ring step 落在哪个物理芯片上（`GetReplicaPair3DOnTwistedTorus`），以及每条 neighbour edge 使用哪条 ICI link（`BuildStrategy` 中的 seam builder）。在 routing 侧，同一个 twist 会重新偏置 `GetDistance` / `GetTiebreak` 的 minimum-hop 路径，使 route table 避开原本会死锁的 link cycle。twist 如何调整 torus-reduced distance vector 见 [Get Distances](../routing/get-distances.md)。

---

## 2. `TwistedTorus` 类族

名称 "twisted torus" 指向**两个**互不相关的 C++ 类型加一个 SparseCore 变体。混淆它们是最容易犯的错误；它们共享几何概念，除此之外没有共同点。

```text
xla::jellyfish::TwistedTorusND                       ── COLLECTIVE STRATEGY (this section)
  derives from StrategyND; constructed by SelectNDStrategy's C-ii twisted branch
  ctor                       0x137d0040   (vtable 0x219242a0)
  UpdateMinMaxDims           0x137d0260   ── K/2K classifier + the twist CHECKs
  InitColorDimensions        0x137d0800   ── `color_dims[6][3]` cyclic fill (or degraded remap)
  BuildStrategy              0x137d0c00   ── base ND ring + per-color seam phases
  seam builders:  UpdateNeighborsKTo2K  0x137d24c0 · UpdateNeighbors2KToK 0x137d29c0
                  UpdateOrdinal2K       0x137d2c60 · UpdateOrdinal2KToK   0x137d28c0
  2-phase groups: GetPhase0ReplicaGroups 0x137d3560 · GetPhase1ReplicaGroups 0x137d3de0
                  GetPhase0Cores         0x137d6de0 · GetPhase1Cores        0x137d6ec0
  GetPerColorShardIdTable    0x137d2d80   ── 1-phase-only gate
  ToStringName               0x137d6da0   ── literally emits "TwistedTorusND"

accel_ssw::deepsea::slice_builder::TwistedTorusTopology   ── ROUTE TABLE (routing section)
  InitRouteSolution          0x20b3f7c0
  GetStaticPath              0x20b407c0 · GetDistance 0x20b408e0 · GetDistances 0x20b420e0
  GetTiebreak                0x20b41320 · GetDistanceFromOrigin 0x20b42980
  UnboundedWalk / Walk / Format / ToProto / Clone …

xla::tpu::sparse_core::collective::TwistedTorusTopologyInfo   ── SPARSECORE collective
  TryCreateTwistedTorusTopologyInfo  0x133e1980 · ConstructTwistedViews 0x133e1ea0

类	命名空间	产出	记录位置
`TwistedTorusND`	`xla::jellyfish`	逐 color ring schedule + HLO `ReplicaGroup` 列表	本节
`TwistedTorusTopology`	`accel_ssw::deepsea::slice_builder`	twisted slice 的静态逐 link route table	routing section
`TwistedTorusTopologyInfo`	`xla::tpu::sparse_core::collective`	SparseCore twisted collective views	SC 侧 Twist

陷阱 - 字面 K_2K_NK（n > 2）几何只由 routing 侧 TwistedTorusTopology 处理（它的 GetTiebreak / GetDistance 会走一个 n-fold-doubled 轴）。jellyfish collective TwistedTorusND 从不会看到 n > 2：UpdateMinMaxDims 的 max_dim == 2*min_dim CHECK 和 GetReplicaPair3DOnTwistedTorus 的 num_max_dims == 2 CHECK 都会对任何不恰好为 K 或 2K 的轴 fatal-error。因此 K_2K_NK slice 在 collective 半边通过与 K_K_2K/K_2K_2K 相同的 num2K ∈ {1,2} 机制折叠，字面 nK 只对 route generator 有意义。见形状折叠。

3. Shape gate 与 shape-fold 目录

在构建任何 ring 之前，TwistedTorusND::UpdateMinMaxDims (0x137d0260) 把三个 torus extent 归约成两个标量和两个计数，并带有两个 fatal CHECK，它们定义了 "twisted" 的含义：

text

min_dim_ (K)        = the short axis size        ([obj+0x5f8])
max_dim_ (2K)       = the long axis size         ([obj+0x5f0])
CHECK:  max_dim_ == 2 * min_dim_                  ("Max. dim size should be 2 times the min. in a twisted torus")
num_max_dims_       = count of axes equal to 2K   ([obj+0x600])   ── decompiled vpcmpeqq
num_min_dims_       = count of axes equal to K    ([obj+0x608])   ── decompiled vpcmpeqq
CHECK:  num_min_dims_ + num_max_dims_ == num_dims_ (==3)   ("Dimension sizes should either be maximum or minimum")
```text

两个 CHECK 字符串都已按原文反编译验证（`0x137d0260` 函数体中的 `MakeCheckOpString`）。`(num-2K-axes, num-K-axes)` 对随后把 slice 分类为三个 `TwistedTorusShape` enum 值之一。enum 和 slice-shape 错误字符串绑定到 proto descriptor 以及 slice_builder `.rodata` 字符串 `"TPU twisted torus only supports k*k*2k and k*2k*2k and k*2k*nk slice shapes."`（在 `CreateTpuSliceTopology` @ `0x1ff939c0` 中确认）。

| 形状 | `TwistedTorusShape` | `num-2K` / `num-K` | Seam 应用于 | Phase0 `R` |
|---|---|---|---|---|
| `K, K, 2K` | `TWIST_SHAPE_K_K_2K` | 1 / 2 | 单个 `2K` 轴（单轴 seam） | `K` |
| `K, 2K, 2K` | `TWIST_SHAPE_K_2K_2K` | 2 / 1 | **两个** `2K` 轴（对角线 `(+K,+K)` seam） | `2K` |
| `K, 2K, nK` | `TWIST_SHAPE_K_2K_NK` | - | collective 按 n=2 情况折叠；字面 `nK` 只在 routing 中使用 | - |

`R = (num-2K-axes >= 2) ? 2K : K` - 也就是说，单个 doubled 轴时 `R = K`，两个 doubled 轴时 `R = 2K`。`R` 是 Phase0 replica-group 构建的外层循环边界（§5）。逐形状坐标折叠表（统一的 `K_2K_2K` 逐 orientation 闭式形式、`K_K_2K` 单轴折叠、以及 `K_2K_NK` 归约）见 [形状折叠](shape-folds.md) 和 [GetReplicaPair3DOnTwistedTorus](get-replica-pair-3d.md)。

> **说明 -** shape classifier 按 `[obj+0xb8]=Y`、`[obj+0xc0]=X`、`[obj+0xc8]=Z` 的顺序读取三个 obj dim 字段（`UpdateMinMaxDims` 加载顺序）。collective 半边全程使用的 loop-variable <-> axis 映射是 `Y<->j`、`X<->i`、`Z<->k`，已从 `GetPhase0ReplicaGroups` 和 `GetPhase1ReplicaGroups` 两者的 `GetReplicaPair3D` call-site push 顺序做字节精确确认。

---

## 4. `BuildStrategy` 阶段顺序

`TwistedTorusND::BuildStrategy` (`0x137d0c00`) 把 `color_dims[6][3]` 表（由 `InitColorDimensions` `0x137d0800` 填充）转成 all-reduce emitter 消费的逐 color ring neighbour/ordinal 表。它分两阶段运行：**base rectangular ND ring** 构建（复用自 `StrategyND`），然后是**逐 color seam overwrite**，用 twist fold 重新连线 `K`/`2K` 轴边。拥有字节级推导的页面是 [TwistedTorusND::BuildStrategy](buildstrategy.md)；这里总结阶段顺序。

**阶段 1 - base ND ring (`0x137d0e62..0x137d13ad`)。** 与基础 `StrategyND::BuildStrategy` 相同的 `[obj+0xa8]==1` ND-ring-vs-1D-ring gate。对每个 color、每个 active dimension，它计算 ring ordinal（`ComputeOrdinal` `0x137c5300`），然后在 no-wrap fast path 上通过 `Torus2DevicePhase0Neighbor` (`0x137c57a0`) 计算 forward/backward neighbour，或在其他情况下通过 `MeshStrideNPhasekNeighbor` (`0x137c5cc0`) 加内联 `ModuloRingSize` fold 计算，并写入逐 color clockwise / counter-clockwise neighbour buffer。这是*未展开的* torus ring；随后 seam phases 覆写 doubled-axis entries。

**阶段 2 - 逐 color、逐 phase seam (`0x137d168a..0x137d1c68`)。** 外层循环是 color `c`（数量 `<=6`）；内层循环是 **ring-dimension phase** `p ∈ {0,1,2}`。对每个 `(c, p)`，循环读取 `color_dims[c][p]`（分配给该 color 的该 ring dimension 的物理轴），并根据该轴是 `K` 轴还是 `2K` 轴分派：

| Phase `p` | `color_dims[c][p]` 是 `K` 轴 | `color_dims[c][p]` 是 `2K` 轴 |
|---|---|---|
| 0 | `UpdateNeighborsKTo2K` + `UpdateOrdinal2KToK` | `UpdateNeighbors2KToK` + `UpdateOrdinal2K` |
| 1 | `UpdateNeighborsKTo2K` + `UpdateOrdinal2KToK` | `UpdateNeighbors2KToK` + `UpdateOrdinal2K` |
| 2 | `UpdateNeighborsKTo2K` + `UpdateOrdinal2KToK` | `UpdateNeighbors2KToK` |

**phase index `p` 是每个 seam-builder 调用的第三个参数**，已反编译验证：三组调用分别传入 `0`、`1`、`2`（例如 `UpdateNeighborsKTo2K(…, 0, …)` -> `(…, 1, …)` -> `(…, 2, …)`）。`K`-axis 列以 **K->2K** 方式 seamed（两个长度为 `K` 的 ring 通过 `UpdateNeighborsKTo2K` + `2KToK` ordinal 首尾相接成一个长度为 `2K` 的 ring）；每个 `2K`-axis 列以 **2K->K** 方式 seamed（`UpdateNeighbors2KToK` + `2K` ordinal）。由于每个 color 的三个 `color_dims` 列都是 `{0,1,2}` 的循环轮换（由 `InitColorDimensions` 填充），每个 color 恰好得到一个 `K->2K` seam phase 和剩余的 `2K->K` phase，且连续 color 会轮换哪个物理轴承载 seam - 从而在 color 之间平衡 doubled-axis ICI 带宽。

```text
BuildStrategy(target, lrb):
    UpdateMinMaxDims(target)            // K, 2K, num-2K, num-K  (§3)
    InitColorDimensions(target)         // `color_dims[6][3]` = cyclic perm mod 3 (or degraded remap)
    identify K-axis index + the one/two 2K-axis indices
    for color c in 0..num_colors-1:     // ≤ 6
        for phase p in 0,1,2:           // p IS the ring-dimension column
            base ND ring neighbours already deposited (Stage 1)
            axis = color_dims[c][p]
            if axis == K-axis:   UpdateNeighborsKTo2K(c, p, …) ; UpdateOrdinal2KToK(c, p, …)
            else  (2K-axis):     UpdateNeighbors2KToK(c, p, …) ; UpdateOrdinal2K(c, p, …)

说明 - InitColorDimensions 首先调用 UseResilientAlgorithmTwistedTorus（0x1c894fc0，与 picker 共享的 env[0x1116] + GetDegradedAxis != -1 gate）。在 degraded axis 上，它尾调用基础 InitColorDimensionsDegraded（0x137c6580）- 同一个 [6][3] remap 会把 dead axis 降级到内层 ring 列。非 resilient 填充是 color_dims[c][d] = (c*stride + d) mod 3。.rodata 注释 "twisted topology should have 3 pairs of colors" 确认了 6 行（3x2）color 结构。

5. 两阶段 collective 与 megacore 拆分

twisted-torus all-reduce 是两个阶段：沿 doubled 2K ring 的 reduce-scatter，然后在正交平面上的 all-gather。每个阶段的 HLO ReplicaGroup 设备列表由 GetPhase0ReplicaGroups / GetPhase1ReplicaGroups 构建；两者首先调用 UpdateMinMaxDims（§3），并通过 GetPhysicalToLogicalMapping3D（0x1c88a280，一个 [Y][X][Z] 表，其叶子是两个 megacore-core 逻辑 ID {core0, core1}）构建 physical->logical device map，然后走 twist 坐标折叠 GetReplicaPair3DOnTwistedTorus（0x1c893400）。完整推导见两阶段 Replica-Group 构建。

Phase	组数量	组索引	成员	扫过的轴
0 - reduce-scatter	`K*R`	`k*R + i`	`2K`（megacore 时 x2），成员索引 `j`	长（`2K`）ring
1 - all-gather	`2K`（或 `4K` megacore-split）	`m` 或 `{2m, 2m+1}`	`R*K`，成员索引 `(i,k)`	与 `2K` ring 正交的平面

Phase0 对每个 (i,k) 收集 twisted ring 在步骤 j = 0..2K-1 放置的 2K 个芯片 - 它就是沿 doubled 轴的 reduce-scatter ring。Phase1 收集第 m 个长轴 slice 的所有 R*K 个芯片（KxR 横截面）- 即 ring 正交平面上的 all-gather。该 collective 仅支持 single-shard：GetPerColorShardIdTable（0x137d2d80）在任何 shard count >= 2 上都会用 "3D twisted torus weight update sharding algorithm currently supports only 1-phase sharding." fatal-error（已反编译验证）。

megacore 偶/奇拆分（仅 Phase1）由逻辑设备数量控制，而不是直接由 megacore 模式控制。Phase1 组数量为 LogicalDevicesPerChip(0) * 2K，其中 LogicalDevicesPerChip(0)（0x20ad3020）= Megacore ? 1 : CoreCount：

模式	`LogicalDevicesPerChip`	Phase1 组	Append 路由
megacore	1	`2K`	组 `m`（两个 core，一个逻辑设备）
非 megacore，1 core	1	`2K`	组 `m`
非 megacore，2 cores	2	`4K`	core0 -> 组 `2m`（偶数），core1 -> 组 `2m+1`（奇数）

因此，偶/奇拆分是非 megacore 2-logical-device 情况，其中两个 core 在互不相交的平面半边上 all-gather，以平衡平面的 ICI link；megacore 芯片把两个物理 core 折叠为一个逻辑参与者，并使用组 m（无拆分）。Phase0（reduce-scatter）总是把芯片的两个 core 共同分到同一个组，而不管 megacore 模式如何（两个 proto append 写入同一个 group pointer）。组数量是 LogicalDevicesPerChip(0)*2K，其中 LogicalDevicesPerChip 通过 Megacore ? 1 : CoreCount getter 解析：CoreCount = 2 -> 4K 个组用于拆分，1 -> 2K 个组用于 megacore。字节精确 gate 和理由见 Megacore 偶/奇拆分；工作负载层面的 megacore 分解见 collectives 章节的 Megacore Collective Fusion。

6. Twist 与 routing 的交汇处

collective 半边（§2-§5）产生 ring schedule 和 replica groups；它不决定每个 hop 由哪些物理 ICI link 承载。那是 routing 半边的工作，而 twist 会在那里重新进入：

accel_ssw::deepsea::slice_builder::TwistedTorusTopology::GetDistance（0x20b408e0）/ GetDistances（0x20b420e0）计算 twist-adjusted torus-reduced distance vector - +K-mod-2K seam 会偏置 doubled 轴上的 minimum-hop count。见 Get Distances。
GetTiebreak（0x20b41320）是在存在两条等距路径时，k*k*2k / k*2k*2k route cache 所依据的规则；预计算的 twisted route cache（…_twisted.binarypb）是 WildFirst generator 在 twisted shapes 上的离线输出。见 routing section 和 Get Tiebreak。
TwistedTorusTopology::InitRouteSolution（0x20b3f7c0）是 resilient InitRouteSolution 的 twisted-shape 同级函数，为 twisted slice 生成逐 link route table。

陷阱 - 两个半边使用不同坐标约定和不同的 "twist" 锚点。jellyfish GetReplicaPair3DOnTwistedTorus 工作在 replica-group / device-id 空间，并在 +K step 处对 2K ring 进行 seam；slice_builder TwistedTorusTopology 工作在物理芯片坐标空间，并对 route distance 进行 seam。重实现者必须同时构建两者 - replica groups 告诉每个 core 与谁一起 reduce，route table 告诉 DMA fabric 字节如何到达那里。混淆两者会得到一个知道伙伴但不知道 link 的 schedule。

7. 函数映射

函数	地址	作用
`TwistedTorusND::TwistedTorusND` (ctor)	`0x137d0040`	由 `SelectNDStrategy` C-ii 构造
`TwistedTorusND::UpdateMinMaxDims`	`0x137d0260`	`K`/`2K` classifier + 两个 twist CHECK
`TwistedTorusND::InitColorDimensions`	`0x137d0800`	`color_dims[6][3]` 循环填充 / degraded remap
`TwistedTorusND::BuildStrategy`	`0x137d0c00`	base ND ring + 逐 color seam phases
`TwistedTorusND::UpdateNeighborsKTo2K`	`0x137d24c0`	`K->2K` neighbour seam
`TwistedTorusND::UpdateNeighbors2KToK`	`0x137d29c0`	`2K->K` neighbour seam
`TwistedTorusND::UpdateOrdinal2K`	`0x137d2c60`	`2K` ordinal fold
`TwistedTorusND::UpdateOrdinal2KToK`	`0x137d28c0`	反向 `2K->K` ordinal fold
`TwistedTorusND::GetPhase0ReplicaGroups`	`0x137d3560`	沿 `2K` 的 RS 组列表
`TwistedTorusND::GetPhase1ReplicaGroups`	`0x137d3de0`	平面上的 AG 组列表 + megacore 拆分
`TwistedTorusND::GetPhase0Cores / GetPhase1Cores`	`0x137d6de0 / 0x137d6ec0`	每阶段 core-ID vector（成本模型）
`TwistedTorusND::GetPerColorShardIdTable`	`0x137d2d80`	1-phase-only gate（Unimplemented string）
`GetReplicaPair3DOnTwistedTorus`	`0x1c893400`	`+K`-mod-`2K` 坐标折叠；`num_max_dims == 2` CHECK
`GetPhysicalToLogicalMapping3D`	`0x1c88a280`	`[Y][X][Z] -> {core0, core1}` map
`TwistedTorusND::ToStringName`	`0x137d6da0`	发出 `"TwistedTorusND"`
`TwistedTorusTopology::InitRouteSolution`	`0x20b3f7c0`	routing 侧 twisted route table
`TwistedTorusTopology::GetTiebreak / GetDistance`	`0x20b41320 / 0x20b408e0`	twisted slice 上的 route distance / tiebreak
`TwistedTorusTopologyInfo::TryCreate…`	`0x133e1980`	SparseCore twisted collective

8. 未解决事项

GetPhase0Cores / GetPhase1Cores 函数体。 ReplicaGroup proto 构建已解码；成本估算器遍历的并行 *Cores device-ID vector（EstimatePhysicalLinksUsed 0x1c8939c0）已定位但未转录。中等。见两阶段 Replica-Group 构建。
routing 侧 K_2K_NK distance 数学。 TwistedTorusTopology::GetTiebreak / GetDistanceFromOrigin（0x20b42980）是字面 nK（n > 2）长轴真正不同的唯一位置；依赖 n 的 distance 公式尚未解码。中等。见 routing section。
>=2-phase（arg>=1）坐标折叠。 GetReplicaPair3DOnTwistedTorus 的 arg==1 入口块（0x1c893535）是结构上不同的 seam，但在 v0.0.40 中由 CHECK gate 标记为不可达（GetPerColorShardIdTable 1-phase gate）。低。见 GetReplicaPair3DOnTwistedTorus。
SparseCore twisted views。 TwistedTorusTopologyInfo::ConstructTwistedViews（0x133e1ea0）- SC Phase groups 是否按不同于 TensorCore 路径的逻辑设备方式拆分 - 已定位但未追踪。中等。见 SC 侧 Twist。

交叉引用

Twist 算法（本节）

TwistedTorusND::BuildStrategy - base ND ring + 逐 color K<->2K seam phase 顺序，字节级
Twist Predicate & Orientation - max == 2*min 谓词和 Orientation/Polarity 维度映射
形状折叠 - K_K_2K / K_2K_2K / K_2K_NK 坐标折叠目录
GetReplicaPair3DOnTwistedTorus - +K-mod-2K 坐标折叠和 num_max_dims == 2 gate
两阶段 Replica-Group 构建 - Phase0 沿 2K 的 RS、Phase1 平面上的 AG
Megacore 偶/奇拆分 - 由 LogicalDevicesPerChip 控制的 Phase1 拆分
Get Tiebreak - twisted slice 上的 route tiebreak 规则
SC 侧 Twist - SparseCore TwistedTorusTopologyInfo 变体

同级章节

SelectNDStrategy - ND Collective-Algorithm Picker - 构造 TwistedTorusND 的 C-ii 分支
On-Pod Collectives - twisted strategy 在 collective lowering 中的位置
Megacore Collective Fusion - 工作负载层面的 megacore 分解
ICI Routing - TwistedTorusTopology route-table 类族和 twist-adjusted GetDistances
Get Distances - twist-adjusted torus-reduced distance vector
返回索引

Twisted Torus - 章节地图 ​

摘要 ​

1. 什么是 twisted torus ​

3. Shape gate 与 shape-fold 目录 ​

5. 两阶段 collective 与 megacore 拆分 ​

6. Twist 与 routing 的交汇处 ​

7. 函数映射 ​

8. 未解决事项 ​

交叉引用 ​

Twist 算法（本节） ​

同级章节 ​