拓扑生成模块设计规格
版本：1.3.1 状态：Accepted 创建日期：2026-04-21 最后更新：2026-05-25 Accepted 日期：2026-05-25 作者：xiang.li 前置：无
变更历史
| 版本 | 日期 | 变更说明 |
|---|---|---|
| 1.3.1 | 2026-05-25 | Patch：实现 review 发现的 spec 笔误——@tbl-spec-topo-23 中 "torus N=30 → 空" 与 §Torus 公式自相矛盾（30=5×6 满足 $\prod S_d=30, S_d\geq2$）；改为 N=23（真质数）保留"无合法多维分解"的空集语义。无新增正文，仅修复 verification case 错误。 |
| 1.3.0 | 2026-05-25 | 重大重构（后端实现前的接口契约冻结）：(1) $C_{\text{board}}$ 从用户输入翻转为派生输出，用户输入收敛为 $N_{\text{chip}}$ + scope + $C_{\text{board,max}}$；(2) Chip 定义修正为 Tier 6 物理封装单元（die 属 Tier 5，不在 spec 范围）；(3) 硬件层级模型新增 chip_radix 字段，族公式支持每 chip 多 link（multi-edge）；(4) Fat-Tree 明确为 PGFT 变体，参数加 $w_i$/$p_i$，端口分配公式严格整除；(5) Dragonfly $g \in [2, ah+1]$ 范围遍历，新增 non-balanced-global-link warning；(6) Ring/Full-mesh 移除 intra-board scope 双模，chip 间互联统一走 IntraBoardTopo；(7) enumerate 接口用 EnumerationContext 对象传输入；(8) warnings 数组语义明确（可叠加，status 单值）；(9) Torus shape 无合法 board_shape 时静默丢弃该候选；(10) 新增 §硬件设计反推章节；(11) §Alternatives 补 5 条拒绝档案；(12) §Success Criteria 验收用例覆盖所有 9 族；(13) MAJOR-1/3/4 + MIN-1/5/7/8/9/10 + NIT 顺手修。SemVer 决策：本次涉及输入契约翻转 + 多个族公式调整 + 新增章节，按 §Drawbacks 风险评级属于设计重构，应升 minor (1.3.0)。Breaking change：v1.2.x 调用方需迁移到新接口。 |
| 1.2.0 | 2026-04-24 | 重写：以 Tier 6-9 硬件层级模型为核心重构整体框架；将实现细节（接口签名、UI 交互）移出 spec，聚焦设计原理和约束理论；补充业界工具调研与枚举派生设计原理 |
| 1.1.0 | 2026-04-23 | 扩展到 9 类拓扑族；引入 chips_per_board + boardGrouping + IntraBoardTopo；名词表 + endpoint→chip 映射 + switchScope 结构化 + boardGrouping 契约 |
| 1.0.0 | 2026-04-21 | 初版：快捷模式拓扑生成 + 探索模式框架 |
@tbl-spec-topo-01 文档变更历史
Summary
拓扑生成模块解决的核心问题是：给定芯片总数和硬件封装约束，在各拓扑族的数学约束下，自动枚举并筛选出工程可行的网络互联方案，同时产出与硬件层级一致的物理分组。
模块是一个约束满足 + 参数空间搜索框架。每个拓扑族（fat-tree、dragonfly、torus 等）定义自己的参数空间和约束规则，框架负责参数校验、层级映射、可行性分档。生成结果可直接用于性能仿真（Math/G5）和 3D 可视化。
Motivation
现状与问题
- 手工配置成本高：一个 32 芯片 fat-tree 拓扑的 YAML 配置有 300+ 行，涉及交换机定义、链路连接、物理分组三部分，重复且易出错
- 参数空间盲目枚举：不加约束地遍历参数会产出大量无工程意义的组合——例如 32 芯片规模下的 3-layer fat-tree（过度设计），或 4 节点的 dragonfly（退化为单 group）。用户需要从数百个"数学合法"的组合中人工挑选
- 生成结果缺物理层级：现有生成器只产出网络图（switches + links），缺少 board→rack→pod 的物理层级分组，无法映射到 3D 可视化
- 层级语义混乱：ring、full-mesh 等小规模族被推荐为跨 rack 主拓扑，与其实际适用的物理层级（board 内 NVLink 互联）不符
驱动力
用户的核心需求是在固定芯片数下快速探索不同互联结构的性能差异。这要求生成器能：
- 过滤掉无意义的参数组合，只呈现工程可行的方案
- 产出完整的物理层级信息，支持端到端的仿真和可视化
- 在不同拓扑族之间提供可比较的输出格式
Terminology
硬件层级：
| 名词 | 定义 | 对应 Tier |
|---|---|---|
| Chip | Tier 6 物理封装单元（加速器封装），可含 1+ die；die 属 Tier 5，是 chip 内部结构，不在本 spec 拓扑生成范围内 | Tier 6 |
| Board | 含 1+ chip 的 PCB 板卡 | Tier 7 |
| Rack | 含 1+ board 的标准 42U 机柜 | Tier 8 |
| Pod | 含 1+ rack 的部署单元（机柜组） | Tier 9 |
| Tier 6-9 | 本 spec 涵盖的 4 级硬件层级模型，Tier 编号越大物理范围越大。Pod ⊃ Rack ⊃ Board ⊃ Chip。Tier 5 (die) 是 chip 内部结构，不暴露到拓扑层 | — |
chip_radix | 单个 chip 对外的 c2c 端口数，硬件参数。Spec 默认假设值为 1；硬件支持多端口时（如 8）需在输入中显式提供，族公式据此决定每 chip 出几 link | — |
@tbl-spec-topo-02 Terminology
连接类型：
| 名词 | 定义 | 跨越的层级 |
|---|---|---|
| C2C | Chip-to-Chip 连接 | Tier 6 内或 Tier 6→7 |
| B2B | Board-to-Board 连接 | Tier 7→8 |
| R2R | Rack-to-Rack 连接 | Tier 8→9 |
| P2P | Pod-to-Pod 连接 | Tier 9 以上 |
@tbl-spec-topo-03 Terminology
拓扑生成核心概念：
| 名词 | 定义 | 区分/补充 |
|---|---|---|
| 拓扑族 (Family) | 一类具有共同数学结构的网络拓扑（如 fat-tree、dragonfly、torus），定义自己的参数空间和约束规则 | — |
| Endpoint | 族生成器的叶子节点抽象——族内最小独立连接单位 | 叶子在 Tier 7 的族：1 endpoint = 1 board；叶子在 Tier 6 的族：1 endpoint = 1 chip |
| $N_{\text{chip}}$ | 芯片总数，用户输入的核心参数 | — |
| $N_{\text{endpoint}}$ | 族产出的 endpoint 数量，由族参数推导（如 Fat-Tree 由 $k, layers, osr$ 推出；Torus 等于 $N_{\text{chip}}$） | 不是用户输入 |
| $C_{\text{board}}$ (chips_per_board) | 每 board 含多少个 chip。派生输出——从族枚举结果反推：Tier 7 叶子族 $C_{\text{board}} = N_{\text{chip}} / N_{\text{endpoint}}$；Tier 6 叶子族 $C_{\text{board}} = \prod B_d$ | 不是用户输入。每个枚举结果带一个 $C_{\text{board}}$ 值，对应一种硬件分组方案 |
| $C_{\text{board,max}}$ | 物理上 PCB 板能承载的 chip 数上限，硬件经验约束。默认 16（业界 dense PCIe carrier 上限） | 用户可选输入；$C_{\text{board}} > C_{\text{board,max}}$ 的枚举结果触发 dense-pcb-impractical warning |
| Scope | 拓扑的物理作用范围，由用户作为输入提供：intra-rack（Tier 7-8）、inter-rack（Tier 8-9+） | 用户输入；族声明自己适用哪些 scope，不匹配标 warning 不硬拒绝 |
| EnumerationContext | enumerate / generate 接口的输入对象，封装 $N_{\text{chip}}$、scope、$C_{\text{board,max}}$、chip_radix、defaults 等所有上下文参数 | 接口扩展时往该对象加字段，不破坏签名 |
| 层级归属 | 网络元素（switch、endpoint）在 Tier 6-9 中的位置。如 fat-tree 的 ToR switch 归属 Tier 8 (Rack) | 由族在生成时声明 |
| 物理分组 (BoardGrouping) | 族产出的 chip → board → rack → pod 嵌套关系，用于 3D 可视化和一致性校验 | — |
@tbl-spec-topo-04 Terminology
枚举与筛选：
| 名词 | 定义 | 区分/补充 |
|---|---|---|
| 枚举 (Enumerate) | 遍历族的参数空间，返回所有满足硬约束的合法参数组合 | 与生成 (Generate) 的关系：枚举找参数，生成产出网络 |
| 生成 (Generate) | 对选定的参数组合，产出完整的网络图和物理分组 | — |
| 正确性约束（硬约束） | 来自拓扑数学性质的硬性要求，违反则不生成（如整除关系、完整填满、连通性） | 与可用性约束的区别：正确性是数学必须，可用性是工程推荐 |
| 可用性约束（软约束） | 数学合法但工程退化/过度设计的软标记，返回结果但标为 edge-case 并附 warning。warnings 可叠加：同一结果可同时触发多条 warning，全部记入 warnings 数组 | 如 32 芯片用 3-layer fat-tree 同时触发 over-engineered 和 low-utilization |
| status | 枚举结果的可行性分档：recommended（无 warning）或 edge-case（≥1 warning）。单值字段 | 与 warnings 数组的关系：warnings.length > 0 ⟺ status == "edge-case" |
| warnings | 该枚举结果触发的所有可用性 warning 数组（可能为空） | 数组语义；验收用例判定使用"warnings 包含 X"而非"warnings 等于 [X]" |
| IntraBoardTopo | Board 内 chip 间互联的唯一表达通道（Tier 6 层），与跨 board 族拓扑（Tier 7+）正交独立。族不感知 IntraBoardTopo | 仅 $C_{\text{board}} > 1$ 时有效；可选 none / full-mesh / ring / torus |
| NetworkGraph | 拓扑生成的核心数据结构，含 nodes（chip + switch）、edges、physical grouping（boards/racks/pods）、metadata（diameter 等指标） | 框架 + 族共同维护；输出供下游路由/仿真/可视化消费 |
| multi-edge | NetworkGraph 允许同一对节点间存在多条并行边（multigraph 形态），用于表达 chip_radix > 1 下每 chip 多 link 接同目标的硬件场景 | 同一对端点 multi-edge 数 $\leq \min(\text{chip\_radix}, \text{switch.port\_count})$（见 invariant 清单） |
@tbl-spec-topo-05 Terminology
Goals / Non-Goals
Goals:
- G1 层级一致性：生成结果与 Tier 6-9 硬件层级模型完全对齐——每个网络元素（芯片、交换机、链路）都有明确的层级归属，物理分组（board/rack/pod）与网络拓扑一致
- G2 约束驱动的枚举：每个族定义正确性约束（硬拒绝）和可用性约束（软警告），枚举阶段即完成筛选，不产出无工程意义的配置
- G3 族覆盖：支持 9 种拓扑族——fat-tree (PGFT)、dragonfly、dragonfly+、torus、hypercube、hyperx、ring、full-mesh、single-switch。其中 fat-tree (PGFT) 2-layer 和 3-layer 是同一族的不同
layers参数取值，合计算 1 个族；@tbl-spec-topo-11 拆 2 行展示是为说明层级跨度差异，族数仍为 9 - G4 格式兼容：生成的网络配置与手写 YAML 格式完全一致，可直接用于 Math/G5 仿真
- G5 可扩展：新增拓扑族只需实现族接口，不修改框架
- G6 硬件设计反推：在硬件设计未冻结的场景下，由拓扑可行集驱动硬件分组决策——$C_{\text{board}}$ 是派生输出而非输入，用户先选拓扑、再看推荐的 board 划分
- G7 路由模块兼容：生成结果与下游路由模块（见 路由模块设计）的输入契约对齐——含 Fat-Tree 的 PGFT
w_levels/p_levels参数、Torus 的dimension_sizes、Dragonfly 的a/p/h等路由策略所需字段
Non-Goals:
- 不做图形化拓扑编辑器（拖拽连线）
- 不硬绑定业界厂商产品（不限定 radix 为 36/40/48/64 等特定值）
- 不替代手写 YAML——生成器是快捷方式，高级用户仍可手写
- 不做自动寻优（给定目标函数搜索最优参数）——这是未来方向
Background / Prior Art
业界拓扑生成器
业界通用仿真工具均采用参数化 + 族选择的模式生成拓扑。以下对比四个有代表性的工具：BookSim 2.0（Stanford，学术标杆）、SST/Merlin（Sandia，DOE 生态）、SimGrid（INRIA，通用分布式仿真）、ASTRA-sim（Meta/Georgia Tech，AI 训练专用，详见项目文档）。另有 CODES（Argonne 国家实验室，HPC 互联仿真，基于 ROSS 并行离散事件引擎，2020 后基本停更）在参数派生设计上有参考价值，一并提及。
参数交互模式
业界工具一致采用"用户填参数 → 工具校验 → 合法则生成 / 不合法则报错"的模式。用户需要预先知道哪些参数组合是合法的：
| 工具 | 配置方式 | 示例 |
|---|---|---|
| BookSim 2.0 | key=value 配置文件 | topology=torus; k=8; n=2 |
| SST/Merlin | Python 脚本 + SST API | dragonfly.hosts_per_router=4 |
| SimGrid | XML 属性 + 参数字符串 | topo_parameters="2;4,4;1,2;1,2" |
| CODES | C 配置文件 | num_routers=8 |
| ASTRA-sim | YAML 按维度配置 | dims: [8, 4, 2] |
@tbl-spec-topo-06 参数交互模式：工具，配置方式
参数校验深度
各工具对参数合法性的校验差异很大：
| 工具 | 值域检查 | 数学关系校验 | 校验时机 | 报错方式 |
|---|---|---|---|---|
| BookSim 2.0 | 几乎无 | 无 | 构造时 assert | 运行时崩溃 |
| SST/Merlin | 仅路由配置 | 不校验 $g = ah+1$ 等约束 | 初始化时 | fatal error |
| SimGrid | 所有参数 > 0 | 有：叶节点数 = 下行链路乘积 | 构造时 | throw + 错误信息 |
| CODES | 整除关系 | 派生方式规避冲突 | 构造时 | tw_error fatal |
| ASTRA-sim | 完全不检查 | 无 | 不校验 | 静默传播 |
@tbl-spec-topo-07 参数校验深度：工具，值域检查
关键发现：只有 SimGrid 验证参数间的数学一致性关系。CODES 采用了一种巧妙的规避策略——只接受一个核心参数（num_routers），其他参数全部公式派生（如 num_groups = num_routers * num_cn + 1），从源头消除参数冲突的可能性。
本模块的差异化设计
本模块与业界工具有三点本质区别：
- 枚举派生取代用户填参：用户不直接填写参数（不需要知道 fat-tree 的 $k$ 应该取什么值），而是由枚举器遍历参数空间，只返回满足约束的合法组合供用户选择。这继承了 CODES 的"派生参数"思想，但更进一步——CODES 从一个参数派生其余参数，我们从零个族参数（仅需 $N_{\text{chip}}$）派生全部合法组合
- 工程可行性分档：在数学合法性之上增加第二档筛选——区分"工程推荐"和"数学合法但工程退化/过度设计"的配置。业界工具无此机制
- 物理层级产出：同时产出与网络拓扑一致的物理层级分组（board→rack→pod）。业界仅 SimGrid（嵌套 zone）、ASTRA-sim（维度=层级）和 SimAI（交换机层级）有类似能力，但均不如本模块的 Tier 6-9 映射系统化
代表性部署参考
| 拓扑族 | 代表部署 | 参考价值 | 项目文档 |
|---|---|---|---|
| Fat-tree (PGFT — Parametric Generalized Fat-Tree, Petrini & Vanneschi 2001) | Meta Fabric、Google Jupiter、NVIDIA SuperPOD | 2/3-layer 结构、超订比概念、PGFT 的 $w_i/p_i$ 参数化 | Fat Tree |
| Dragonfly | Cray Cascade XC (Kim et al., ISCA 2008) | 组内全互联 + 组间全局链路 | Dragonfly |
| Dragonfly+ | HPE Cray Slingshot | 子组结构，改善路径多样性 | Dragonfly+ |
| Torus | Google TPU v3/v4、Fujitsu Fugaku | 多维环面、坐标映射 | Torus |
| HyperX | Ahn et al., SC 2009 | 多维全互联，Flattened Butterfly 特例 | HyperX |
| Hypercube | Caltech Cosmic Cube | 学术参考，现代无部署 | Hypercube |
@tbl-spec-topo-08 代表性部署参考：拓扑族，代表部署
Guide-Level Explanation
核心思路
拓扑生成的本质是一个两阶段约束满足问题：
第一阶段（枚举）：在族的参数空间中搜索满足硬约束的所有参数组合，并按工程可行性分档标记。
第二阶段（生成）：对选定的参数组合，产出完整的网络结构（交换机 + 链路）和物理层级分组（chip → board → rack → pod），两者必须一致。
典型场景
用户设定芯片总数（如 64）、scope（intra-rack / inter-rack）和可选的 $C_{\text{board,max}}$（默认 16），选择一个拓扑族（如 fat-tree）。框架自动遍历该族的参数空间，返回所有满足硬约束的合法参数组合；每个组合附带一个派生的 $C_{\text{board}}$ 值，对应一种硬件分组方案（例：Fat-Tree k=4 推出 $C_{\text{board}}=8$，k=8 推出 $C_{\text{board}}=4$）。每个组合标注为 recommended 或 edge-case 并附带 warnings 数组（如 over-engineered、degenerate、dense-pcb-impractical）。用户从中选择一个，框架生成完整的网络配置（交换机 + 链路）和物理层级分组（chip → board → rack → pod）。
用户可以切换族对比——同一规模下 fat-tree 可能有多个 $C_{\text{board}}$ 候选，dragonfly 可能全部标为 degenerate（规模过小），torus 可能在某些 shape 下找不到合法 board 划分。用户输入中不包含 $C_{\text{board}}$——硬件分组是输出，不是输入。
与传统"先硬件后拓扑"流程的区别：业界工具假设用户已知硬件（DGX 8 GPU/board），先填硬件参数，再选拓扑。本模块支持硬件未冻结的早期设计阶段——用户用拓扑探索来反推硬件设计（例："如果想跑 k=8 Fat-Tree，PCB 上应该放 4 chip"）。详见 硬件设计反推 章节。
Detailed Design
硬件层级模型
本项目的硬件层级是一个 4 级嵌套结构。拓扑生成的所有概念都必须映射到这个模型：
| 层级 | 硬件单元 | 物理含义 | 典型互联技术 | 带宽量级 |
|---|---|---|---|---|
| Tier 6 | Chip（芯片） | 单个加速器封装（可含 1+ die；die 属 Tier 5，是 chip 内部结构，不在本 spec 范围） | NVLink、C2C | ~900 GB/s |
| Tier 7 | Board（板卡） | 含 1+ chip 的 PCB | PCIe、Board 内总线 | ~64 GB/s |
| Tier 8 | Rack（机柜） | 含 1+ board 的标准 42U 机柜 | InfiniBand、RoCE | ~50 GB/s |
| Tier 9 | Pod（机柜组） | 含 1+ rack 的部署单元 | IB Fabric、Ethernet | ~50 GB/s |
@tbl-spec-topo-09 硬件层级模型：层级，硬件单元
chip_radix 字段：每个 chip 对外的 c2c 端口数。Spec 默认 1（"每 chip 每族出 1 link"），硬件实际支持多端口时需在 EnumerationContext 中显式提供（例：硬件 chip 8 端口 → chip_radix = 8）。族公式可基于 chip_radix 决定每 chip 出几条 link（multi-edge）——同一对 chip / 同一 chip-to-switch 之间允许多条并行链路；输出的 NetworkGraph 是 multigraph 形态。
层级间的包含关系：Pod ⊃ Rack ⊃ Board ⊃ Chip。每个上层单元包含 1 个或多个下层单元。
连接类型与层级的对应：
| 连接类型 | 含义 | 跨越的层级边界 |
|---|---|---|
| C2C | Chip-to-Chip | Tier 6 内（board 内）或 Tier 6→7 边界（board 间） |
| B2B | Board-to-Board | Tier 7→8 边界（rack 内） |
| R2R | Rack-to-Rack | Tier 8→9 边界（pod 内） |
| P2P | Pod-to-Pod | Tier 9 以上 |
@tbl-spec-topo-10 硬件层级模型：连接类型，含义
拓扑族的层级跨度
每个拓扑族在硬件层级上有明确的操作范围——它的叶子节点（endpoint）落在哪个 tier，它的网络结构向上延伸到哪个 tier：
| 族 | 叶子 tier | 根 tier | 层级跨度 | 说明 |
|---|---|---|---|---|
| Fat-tree 2-layer | Tier 7 (Board) | Tier 8-9 (Rack-Pod) | 2-3 级 | Leaf 连 board，Spine 跨 rack |
| Fat-tree 3-layer | Tier 7 (Board) | Tier 9+ (Pod+) | 3-4 级 | ToR→Rack, Agg→Pod, Core→跨 Pod |
| Dragonfly | Tier 7 (Board) | Tier 8-9 (Rack-Pod) | 2-3 级 | Group 对应 rack，group 间跨 rack |
| Dragonfly+ | Tier 7 (Board) | Tier 8-9 | 2-3 级 | 同 Dragonfly，子组结构 |
| Torus | Tier 6 (Chip) | Tier 6-8 | 1-3 级 | 芯片直连，坐标映射到 board/rack |
| Hypercube | Tier 6 (Chip) | Tier 6-7 | 1-2 级 | 芯片直连，二进制地址寻址 |
| HyperX | Tier 7 (Board) | Tier 7-8 | 1-2 级 | 交换机挂 endpoint，维度全互联 |
| Ring | Tier 7 (Board) | Tier 7-8 | 1 级 | board 间环 |
| Full-mesh | Tier 7 (Board) | Tier 7-8 | 1 级 | board 间全互联 |
| Single-switch | Tier 7 (Board) | Tier 8 (Rack) | 1-2 级 | 单交换机汇聚 |
@tbl-spec-topo-11 拓扑族的层级跨度：族，叶子 tier
关键观察：
- 有交换机的族（fat-tree、dragonfly、hyperx、single-switch）的叶子是 Board（Tier 7），因为交换机通过线缆连接的是板卡，不是裸芯片
- 直连族（torus、hypercube）的叶子是 Chip（Tier 6），因为芯片间不经过交换机
- Ring 和 Full-mesh 只操作 Tier 7（board 间）——chip 间互联（Tier 6）统一由 IntraBoardTopo 表达。本 spec v1.3 移除了 v1.2 的"双模 scope"设计——避免与 IntraBoardTopo 职责重叠
Endpoint 抽象与层级映射
为什么需要 endpoint：不同族的叶子节点落在不同的 tier。fat-tree 的叶子是 board，torus 的叶子是 chip。为了让框架统一处理，引入 endpoint 作为"族内最小独立连接单位"的抽象。
关键设计：派生方向
本 spec v1.3 翻转了 v1.2 的派生方向——$C_{\text{board}}$ 不再是用户输入，而是从族枚举结果反推的派生值。理由见 硬件设计反推 章节。
endpoint 与硬件层级的关系：
对于叶子在 Tier 7 (Board) 的族（Fat-Tree、Dragonfly、Dragonfly+、HyperX、Ring、Full-mesh、Single-switch）：
族参数（如 Fat-Tree 的 $k, layers, osr$）决定 $N_{\text{endpoint}}$（族自身能容纳的 endpoint 数，等于 board 数）。$C_{\text{board}}$ 从 $N_{\text{chip}}$ 与 $N_{\text{endpoint}}$ 反推：
$$\begin{equation} C_{\text{board}} = \frac{N_{\text{chip}}}{N_{\text{endpoint}}} \label{eq:topo-endpoint-count} \end{equation}$$正确性约束：$N_{\text{endpoint}} \mid N_{\text{chip}}$。不能整除的族参数组合直接丢弃（不返回枚举结果）。
此时 1 endpoint = 1 board，每 board 含 $C_{\text{board}}$ 个 chip，board 内 chip 间的连接由 IntraBoardTopo 机制补充。
对于叶子在 Tier 6 (Chip) 的族（Torus、Hypercube）：
$$\begin{equation} N_{\text{endpoint}} = N_{\text{chip}} \label{eq:topo-endpoint-chip-level} \end{equation}$$此时 1 endpoint = 1 chip，族生成器直接以芯片为单位构建网络。$C_{\text{board}}$ 由 board 分组参数决定（见下文 Torus 的 board_shape 推导）。
Torus 的 board 分组：Torus 是唯一的"叶子在 Tier 6 且需要枚举 board 分组"的族。在 torus 中，endpoint = chip，但多个相邻 chip（坐标空间中的一个立方体）可以聚合为一个 board。族穷举所有合法 board_shape作为独立枚举结果：
$$\begin{equation} N_{\text{board}} = \prod_{d=1}^{D} \frac{S_d}{B_d}, \quad C_{\text{board}} = \prod_{d=1}^{D} B_d \label{eq:topo-torus-board-count} \end{equation}$$其中 $S_d$ 为第 $d$ 维的 torus 尺寸，$B_d$ 为第 $d$ 维的 board 切分尺寸。每个 $(S, B)$ 配对成为一个独立的枚举结果（携带不同的派生 $C_{\text{board}}$）。
$C_{\text{board,max}}$ 软约束：所有族产出的 $C_{\text{board}} > C_{\text{board,max}}$（默认 16）的枚举结果触发 dense-pcb-impractical warning，但不硬拒绝——用户可手动调高 $C_{\text{board,max}}$ 看完整结果集。
生成管线
生成管线的设计原则是关注点分离：族只负责自己的网络图生成，框架负责层级映射和物理分组的一致性。
输入契约：
enumerate 和 generate 接口都通过 EnumerationContext 对象传入参数。该对象封装：
| 字段 | 类型 | 必填 | 默认 | 含义 |
|---|---|---|---|---|
n_chip | int | 是 | — | 芯片总数 |
scope | enum | 是 | — | intra-rack 或 inter-rack |
chips_per_board_max | int | 否 | 16 | $C_{\text{board}}$ 派生值的物理上限。合规说明：项目 rule config-loading.md 禁止配置文件加载时使用默认值，但此处的 16 不是配置文件默认值——它是框架内部用作 warning 触发阈值的基准，未由用户提供时仅用于决定哪些枚举结果带 dense-pcb-impractical warning，不影响合法性判定。若加载用户配置文件时该字段缺失，应当由配置加载层 raise（按 config-loading rule）；框架内部使用时按 16 触发软警告 |
chip_radix | int | 否 | 1 | 单 chip 对外 c2c 端口数 |
intra_board_topo | enum | 否 | none | board 内 chip 互联类型：none / full-mesh / ring / torus |
defaults | dict | 否 | {} | 继承的链路/switch 默认参数（带宽、延迟等） |
@tbl-spec-topo-21a EnumerationContext 输入字段
不接受的字段（已从用户输入移除）：
chips_per_boardRing/Full-mesh 的——chip 间互联通过intra-boardscopeintra_board_topo字段表达
管线分为三个阶段：
阶段一：参数校验
框架验证 EnumerationContext 字段：
n_chip ≥ 2scope ∈ {intra-rack, inter-rack}chip_radix ≥ 1intra_board_topo与族层级跨度的兼容性（如 Torus 不允许intra_board_topo非none，因为 Torus 自身已覆盖 chip 间连接）- scope 与族的适用 scope 列表是否匹配（不匹配不硬拒绝，标
non-standard-scopewarning）
阶段二：族枚举与生成
族接收 EnumerationContext 和族参数，产出：
- 族参数组合：枚举遍历族参数空间，对每组合检查正确性约束
- 派生 $C_{\text{board}}$：按公式 $\eqref{eq:topo-endpoint-count}$ 或 $\eqref{eq:topo-torus-board-count}$ 反推
- 网络图：交换机列表 + 链路列表（端点为 endpoint ID），支持 multi-edge（同一对端点可有多条并行链路）
- 层级归属：每个网络元素（endpoint、switch）归属于哪个硬件层级，以及属于哪个物理容器（哪个 rack、哪个 pod）
- Board 映射：endpoint 到 board 的分组（哪些 chip 组成一个 board）
族产出的层级归属必须与族的层级跨度一致——fat-tree 的 ToR switch 必须归属 Rack 级，不能声称在 Board 级。
阶段三：框架后处理
框架对族的产出做两件事：
- endpoint → chip 展开：对于叶子在 Tier 7 的族，每个 endpoint 展开为 $C_{\text{board}}$ 个 chip；对于叶子在 Tier 6 的族，endpoint 已经是 chip，无需展开
- IntraBoardTopo 补链：若 $C_{\text{board}} > 1$ 且
intra_board_topo ≠ none，为每个 board 内的 chip 补充 Tier 6 层的连接。这些连接与族产出的跨 board 连接独立
设计理由：
- 为什么 endpoint→chip 展开由框架做而非族做？ 因为这是一个与族无关的机械映射——所有叶子在 Tier 7 的族都遵循相同的展开规则。放在框架中避免了每个族重复实现
- 为什么 IntraBoardTopo 是框架职责？ 因为 board 内连接（Tier 6）与跨 board 的族拓扑（Tier 7+）在不同层级，正交独立。族不需要知道 board 内的芯片是 NVLink full-mesh 还是 ring——这是封装层面的决策，不是网络拓扑决策
- 为什么 $C_{\text{board}}$ 派生而非输入？ 见 硬件设计反推 章节
枚举派生：从"用户填参数"到"框架搜索参数"
业界工具的交互模式是"用户填参数 → 校验 → 合法则生成 / 不合法则报错"。这要求用户预先理解每个族的约束关系——例如 fat-tree 的 $k$ 必须为偶数且 $d \mid N_{\text{endpoint}}$，dragonfly 的 $h \leq a$ 且 $g \cdot a \cdot p \geq N_{\text{endpoint}}$。用户试错成本高，且容易错过合法但非直觉的参数组合。
本模块采用枚举派生模式：用户只提供 $N_{\text{chip}}$、scope（和可选的 $C_{\text{board,max}}$、chip_radix、intra_board_topo），框架自动遍历族的参数空间，只返回满足所有硬约束的合法组合，$C_{\text{board}}$ 作为每个结果的派生输出。用户从结果中选择，而非自己构造参数。
与 CODES 的关系：CODES 的"单参数派生"思想是本设计的灵感来源。CODES 只接受 num_routers 一个输入，其余参数由公式派生，从源头消除参数冲突。本模块更进一步——用户不需要提供任何族参数，枚举器穷举整个参数空间的合法子集。
枚举的搜索策略：
每个族定义自己的参数空间边界和遍历顺序。以 fat-tree 为例：
- 遍历 $k \in [4, 64]$（步长 2）× $osr \in \{1, 2, 3\}$ × $layers \in \{2, 3\}$
- 对每个组合检查正确性约束（$d \mid N_{\text{endpoint}}$、容量充足等）
- 通过约束的组合进入可用性分档
- 不通过的组合直接丢弃，用户永远不会看到
用户可选的参数过滤：枚举返回所有合法组合后，用户可以在 UI 上按特定参数值过滤（如只看 $k = 16$ 的结果）。这是后置过滤，不是前置约束——不会遗漏合法组合。
可行性分档
枚举产出的每个参数组合经过两级筛选：
第一级：正确性约束（硬拒绝）
违反即不返回，不生成。这些约束来自拓扑的数学性质，违反后生成的网络不是一个有效的该族拓扑。
正确性约束的共性原则：
- 完整填满：所有 endpoint 都被网络覆盖，无孤立节点
- 对称性保持：族定义的对称性不被破坏（如 torus 的环形对称、fat-tree 的层级对称）
- 连通性：生成的网络图是全连通的
- 参数值域：参数满足族定义的取值范围和整除关系
第二级：可用性约束（软标记，可叠加）
参数数学合法但工程上退化或不推荐。返回结果但标记为 edge-case 并附带 warnings。warnings 是数组——同一结果可触发多条 warning，全部记入数组（如 dragonfly N=32 同时触发 degenerate + low-utilization）；status 字段是单值（recommended 或 edge-case），与 warnings 数组长度的关系：warnings.length > 0 ⟺ status == "edge-case"。
可用性约束的共性原则：
- 规模匹配：族的设计规模与实际芯片数匹配（fat-tree 3-layer 用于 < 256 endpoint → 过度设计）
- 资源效率：容量利用率不过低（总容量 > 1.5× 实际需求 → 浪费）
- 层级适用：族的层级跨度与 scope 匹配（ring 用于 inter-rack → 非标准用法）
- 参数退化：参数选择导致族退化为更简单的结构（dragonfly 单 group → 退化为 full-mesh）
- 硬件物理约束：派生 $C_{\text{board}} > C_{\text{board,max}}$ →
dense-pcb-impractical
所有可用性警告的阈值（如 256、64、128、32、16、$C_{\text{board,max}}$）均为项目经验值——基于 §代表性部署参考的业界规模和 PCB 物理约束估算，可在框架配置中调整。具体值不引用单一来源，是综合工程经验估计。
拓扑族规格
Fat-Tree (PGFT — Parametric Generalized Fat-Tree)
详见 网络拓扑文档 - Fat Tree 参考：Petrini & Vanneschi 2001, "k-ary n-trees: High Performance Networks for Massively Parallel Architectures"（PGFT 原始论文）
层级跨度：Tier 7 (Board) → Tier 8-9+ (Rack-Pod-Datacenter)
设计原理：分层交换网络，通过多级交换机实现无阻塞（或低超订）互联。本族实现遵循 PGFT 严格定义——每层有显式的 $w_i$（上行端口数）和 $p_i$（parent group 大小）参数，保证拓扑层级对称性。2-layer (Spine-Leaf) 适用于单 rack 到少量 rack 场景；3-layer (ToR + Aggregation + Core) 适用于多 rack/多 pod 的数据中心级部署。
为什么明确为 PGFT：项目下游路由模块（详见 路由模块设计 v1.3.1）已实现 D-mod-k 作为 Fat-Tree 专属路由，其 attrs schema 要求 w_levels: list[int] 和 p_levels: list[int]。Spec 必须输出这些字段才能与路由模块对接。Generic Clos 不带这些参数化结构，无法支持 D-mod-k。
参数：
| 参数 | 含义 | 范围 | 默认 |
|---|---|---|---|
layers | 网络层数 | 2 或 3 | auto |
k | 交换机端口数（radix），必须偶数 | 4 ~ 64 | auto |
osr | 超订比（下行：上行） | 1 ~ 3 | 1 |
w_levels | PGFT 各层上行端口数（派生） | [u, ...] 长度 = layers | 由 $k, osr$ 推导 |
p_levels | PGFT 各层 parent group 大小（派生） | [1, ...] k-ary n-tree 形态 | 由 $k, osr$ 推导 |
@tbl-spec-topo-12 Fat-Tree (PGFT) 参数
由 $k$ 和 $osr$ 推导端口分配——$d$ 和 $u$ 必须为整数（PGFT 不允许非整数端口）：
$$\begin{equation} d \cdot (osr + 1) = k \cdot osr, \quad u = k - d \label{eq:topo-ft-port-split} \end{equation}$$其中 $d$ 为下行端口数（连接 endpoint），$u$ 为上行端口数。若公式无整数解，该 $(k, osr)$ 组合丢弃——例如 $k = 4, osr = 2$ 解出 $d = 8/3$ 非整数，丢弃；$k = 6, osr = 2$ 解出 $d = 4, u = 2$ 合法。
$(w_i, p_i)$ 派生：k-ary n-tree 标准形态 $w_i = u, p_i = 1$（即 $w_{\text{levels}} = [u, u, ...]$，$p_{\text{levels}} = [1, 1, ...]$，长度 = layers）。Spec v1.3 暂不支持非 k-ary n-tree 形态的 PGFT 变体（如非均匀 $w_i$），加入待办（详见 Future Possibilities）。
Fat-Tree 的容量由交换机端口分配和层数决定。
2-layer 容量：
$$\begin{equation} N_{\text{leaf}} = \frac{N_{\text{endpoint}}}{d}, \quad N_{\text{spine}} = u \label{eq:topo-ft-2layer} \end{equation}$$3-layer 容量：
$$\begin{equation} C_{\text{3layer}} = d^2 \cdot k, \quad N_{\text{ft\_group}} = \left\lceil \frac{N_{\text{endpoint}}}{d^2} \right\rceil \label{eq:topo-ft-3layer-capacity} \end{equation}$$每 fat-tree group（注：与硬件 Tier 9 Pod 区分——避免命名冲突，v1.2 旧称"fat-tree pod"已改）含 $d$ 个 ToR 和 $u$ 个 Aggregation 交换机，fat-tree group 间由 $u^2$ 个 Core 交换机互联。
正确性约束：
- $k$ 为偶数
- 公式 $\eqref{eq:topo-ft-port-split}$ 有整数解（$(osr+1) \mid k \cdot osr$）
- 2-layer：$d \mid N_{\text{endpoint}}$ 且 $u \leq N_{\text{leaf}}$
- 3-layer：$C_{\text{3layer}} \geq N_{\text{endpoint}}$
- 派生 $N_{\text{endpoint}} \mid N_{\text{chip}}$（保证 $C_{\text{board}}$ 整数）
可用性警告（阈值为项目经验值，可配置）：
layers == 3且 $N_{\text{endpoint}} < 256$ →over-engineered- $osr \geq 2$ →
aggressive-oversubscription（AI 训练的 AllReduce 对带宽敏感） - $k > 64$ →
radix-too-large（基于 2024 主流交换机端口数上限）
层级归属：
| 交换机类型 | 归属层级 | 物理含义 |
|---|---|---|
| ToR / Leaf | Tier 8 (Rack) | 每个 ToR 下挂的 $d$ 个 board 构成一个 rack |
| Aggregation | Tier 9 (Pod) | 每个 fat-tree pod 的 $u$ 个 Agg 交换机属于同一个 pod |
| Core | Tier 9+ (Datacenter) | Core 交换机跨 pod，属于数据中心级 |
@tbl-spec-topo-13 Fat-Tree (PGFT)：交换机类型，归属层级
Board 映射：1 endpoint ↔ 1 board。Board 内 chip 走 IntraBoardTopo。
物理分组：
- 2-layer：每 leaf 下挂 $d$ 个 board = 1 rack，共 $N_{\text{leaf}}$ 个 rack，单 Tier 9 Pod
- 3-layer：每 fat-tree group 含 $d$ 个 rack，共 $N_{\text{ft\_group}}$ 个 fat-tree group，所有 fat-tree group 共享单 Tier 9 Pod（或按需扩展到 Tier 9+）
Dragonfly
层级跨度：Tier 7 (Board) → Tier 8-9 (Rack-Pod)
设计原理：两级分层拓扑，用最少的全局链路实现低直径互联。组内交换机全互联提供高局部带宽，组间全局链路提供全局可达性。适用于中大规模（≥ 64 endpoint）的跨 rack 部署。
参考：Kim et al., "Technology-Driven, Highly-Scalable Dragonfly Topology" (ISCA 2008)
参数：
| 参数 | 含义 | 范围 | 默认 |
|---|---|---|---|
p | 每交换机下挂 endpoint 数 | 2 ~ 8 | auto |
a | 每组交换机数 | 4 ~ 32 | auto |
h | 每交换机全局链路数 | 1 ~ a | auto |
@tbl-spec-topo-14 Dragonfly 参数
Dragonfly 的容量由 $a, p$ 和组数 $g$ 共同决定。$g$ 是独立参数，遍历范围 $g \in [2, ah+1]$：
$$\begin{equation} g \in [2, ah + 1], \quad C_{\text{dragonfly}} = g \cdot a \cdot p \label{eq:topo-df-capacity} \end{equation}$$其中 $g = ah + 1$ 对应 Kim 2008 经典推导的 balanced Dragonfly——保证任意两组间至少一条全局路径且组数上界——是性能最优解；但 $g < ah + 1$ 也合法，对应实际部署中按机柜数决定 $g$ 的常见场景（如 Cray Cascade XC 系列）。每组 $a$ 个交换机，每交换机挂 $p$ 个 endpoint。
正确性约束：
- $h \leq a$
- $g \geq 2$（单 group 退化为 full-mesh，由 Dragonfly 族 degenerate warning 标记，不在此族返回）
- $C_{\text{dragonfly}} \geq N_{\text{endpoint}}$
- 不允许空 group（最后一个 group 至少含 1 个 endpoint）
- 派生 $N_{\text{endpoint}} \mid N_{\text{chip}}$
可用性警告（阈值为项目经验值，可配置）：
- $N_{\text{endpoint}} < 64$ →
degenerate（规模过小，dragonfly 层级结构无意义） - $g = 1$（不再返回，但保留 warning 定义供未来扩展）→
degenerate - $g < ah + 1$ →
non-balanced-global-link（global link 利用率次优，但更接近实际部署） - $C_{\text{dragonfly}} > 1.5 \cdot N_{\text{endpoint}}$ →
low-utilization
层级归属：每个 dragonfly group 对应一个 rack（Tier 8）。Group 内 $a$ 个交换机 + $a \cdot p$ 个 endpoint 共处同一 rack。所有 group 共享一个 pod（Tier 9）。
Board 映射：1 endpoint ↔ 1 board。Board 内 chip 走 IntraBoardTopo。
Dragonfly+
层级跨度：Tier 7 (Board) → Tier 8-9 (Rack-Pod)
设计原理：Dragonfly 的改进型。组内进一步分为子组，子组内全互联 + spine 连接，改善组间路径多样性（原始 Dragonfly 的组间路径瓶颈）。
参数：
| 参数 | 含义 | 范围 | 默认 |
|---|---|---|---|
p | 每叶交换机下挂 endpoint 数 | 2 ~ 8 | auto |
a | 每组叶交换机数，$s \mid a$ | 4 ~ 32 | auto |
s | 每组子组数 | 2 ~ 8 | auto |
@tbl-spec-topo-15 Dragonfly+ 参数
参考：Shpiner et al. 2017, "Dragonfly+: Low Cost Topology for Scaling Datacenters"
Dragonfly+ 的容量由子组结构决定。$g$ 是独立参数，遍历范围 $g \in [2, s(s-1)+1]$：
$$\begin{equation} k = \frac{a}{s}, \quad g \in [2, s(s-1) + 1], \quad C_{\text{df+}} = g \cdot a \cdot p \label{eq:topo-dfplus-capacity} \end{equation}$$其中 $g = s(s-1)+1$ 对应 spine 间全互联（每子组 $s-1$ 个上行端口接其他 $g-1$ 个 group，整除推出 $g_{\max} = s(s-1)+1$）的 balanced 形态，是路径多样性最优解；$g < s(s-1)+1$ 也合法，对应实际部署按机柜数取 group 数。
正确性约束：
- $s \mid a$（$a$ 必须被 $s$ 整除）
- $s \geq 2$
- $g \geq 2$
- $C_{\text{df+}} \geq N_{\text{endpoint}}$
- 不允许空 group
- 派生 $N_{\text{endpoint}} \mid N_{\text{chip}}$
可用性警告（阈值为项目经验值，可配置）：
- $N_{\text{endpoint}} < 128$ →
over-engineered - $s = 2$ →
minimal-subgroups（子组结构优势不明显） - $g < s(s-1) + 1$ →
non-balanced-global-link - $C_{\text{df+}} > 1.5 \cdot N_{\text{endpoint}}$ →
low-utilization
层级归属 / Board 映射：同 Dragonfly。
Torus
层级跨度：Tier 6 (Chip) → Tier 6-8 (Chip-Board-Rack)
设计原理：$D$ 维环面拓扑，每维首尾相连。Torus 的核心优势是完美对称性——每个节点的度数和局部结构完全相同，带宽分析和路由设计因此简化。这要求网格完整填满，缺损节点会破坏环形对称性。
参考：Google TPU v3/v4 (2D/3D torus)，Fujitsu Fugaku (6D torus)
参数：
| 参数 | 含义 | 范围 | 默认 |
|---|---|---|---|
dimensions | 维度数 | 2 或 3 | 遍历 {2, 3} |
shape | 各维长度 $S_d$ | $\prod S_d = N_{\text{endpoint}}$ | 遍历所有合法因子分解 |
board_shape | board 切分形状 $B_d$ | 每维 $B_d \mid S_d$ + 形状语义约束 | 遍历所有合法切分（每个有效切分产出独立枚举结果） |
@tbl-spec-topo-16 Torus 参数
填满约束：
$$\begin{equation} \prod_{d=1}^{D} S_d = N_{\text{endpoint}} = N_{\text{chip}} \label{eq:topo-torus-fill} \end{equation}$$注意 Torus 的 endpoint = chip（叶子在 Tier 6）。
Board 映射约束（每个有效 $B_d$ 产出独立枚举结果，附派生 $C_{\text{board}}$）：
$$\begin{equation} \forall d: B_d \mid S_d, \quad C_{\text{board}} = \prod_{d=1}^{D} B_d \label{eq:topo-torus-board-constraint} \end{equation}$$形状语义约束：若 $\prod B_d > 1$，禁止退化形状（如 $[8, 1, 1]$——链而非 cube）：
$$\begin{equation} \frac{\max(B_d)}{\min(B_d)} \leq 2 \label{eq:topo-torus-shape-ratio} \end{equation}$$（$B_d \geq 1$ 保证 $\min(B_d) \geq 1$，分母不会为零。）
枚举规则：对每个合法 shape $S$，穷举所有满足 $\eqref{eq:topo-torus-board-constraint}$ 和 $\eqref{eq:topo-torus-shape-ratio}$ 的 $B$。每个 $(S, B)$ 对成为一个独立的枚举结果。若某 shape $S$ 找不到任何合法 $B$，该 shape 候选静默丢弃（不返回结果），但同 $N_{\text{chip}}$ 下的其他 shape 不受影响。若所有合法 shape 都被丢弃，整个 enumerate 返回空数组（参考 Success Criteria 中 $N_{\text{chip}} = 30$ 用例）。
注：由于 $B$ 不再外部约束，多个 $(S, B)$ 组合可对应不同的 $C_{\text{board}}$ 值，用户在结果集中按需选取。
正确性约束：
- 公式 $\eqref{eq:topo-torus-fill}$ 严格成立（不允许截断）
- $\forall d: S_d \geq 2$
- 至少存在一组 $B$ 满足 $\eqref{eq:topo-torus-board-constraint}$ 和 $\eqref{eq:topo-torus-shape-ratio}$
可用性警告（阈值为项目经验值，可配置）：
- $\max(S_d) / \min(S_d) > 4$ →
asymmetric（各维严重不均衡） - $\min(S_d) = 2$ →
degenerate-dimension（某维退化为仅 2 节点） - 派生 $C_{\text{board}} > C_{\text{board,max}}$ →
dense-pcb-impractical
层级归属：Torus 无交换机。Chip 直连，board 由坐标 cube packing 决定。默认单 rack 单 pod。
设计理由——为什么 Torus 强制完整填满：Torus 的对称性和带宽保证依赖完整环形结构。缺损 torus 导致：直径分析不再成立、路由从确定性变为自适应、带宽不再均匀。业界也不部署不完整 torus。
Hypercube
层级跨度：Tier 6 (Chip) → Tier 6-7 (Chip-Board)
设计原理：$n$ 维超立方体。$2^n$ 个节点，每节点度数 $n$，两节点相连当且仅当其 $n$-bit 二进制地址恰差 1 位。学术/教学价值，现代 AI/HPC 无实际部署。
参数：
| 参数 | 含义 | 范围 | 默认 |
|---|---|---|---|
n | 维度数 | 1 ~ 10 | auto |
@tbl-spec-topo-17 Hypercube 参数
容量约束：
$$\begin{equation} N_{\text{endpoint}} = N_{\text{chip}} = 2^n \label{eq:topo-hc-capacity} \end{equation}$$正确性约束：$N_{\text{chip}}$ 恰为 $2^n$（严格相等）。
可用性警告（阈值为项目经验值，可配置）：
- 所有配置默认标
research-only - $n \geq 8$ →
high-dimension - 派生 $C_{\text{board}} > C_{\text{board,max}}$ →
dense-pcb-impractical（Hypercube 默认 1 chip = 1 board，$C_{\text{board}} = 1$；如未来支持 board 切分则触发）
层级归属：无交换机。Chip 直连，1 endpoint ↔ 1 board。单 rack 单 pod。
HyperX
层级跨度：Tier 7 (Board) → Tier 7-8 (Board-Rack)
设计原理：$L$ 维层级全互联网络。每维 $S_i$ 个交换机全互联，每交换机挂 $T$ 个 endpoint。当 $L = 2$ 且各维等长时退化为 Flattened Butterfly。
参考：Ahn et al., "HyperX: Topology, Routing, and Packaging of Efficient Large-Scale Networks" (SC 2009)
参数：
| 参数 | 含义 | 范围 | 默认 |
|---|---|---|---|
L | 维度数 | 1 ~ 4 | auto |
T | 每交换机下挂 endpoint 数 | 1 ~ 8 | auto |
S | 各维交换机数 | $S_i \geq 2$ | auto |
@tbl-spec-topo-18 HyperX 参数
HyperX 的容量由各维交换机数量和每交换机端点数决定：
$$\begin{equation} N_{\text{switch}} = \prod_{i=1}^{L} S_i, \quad C_{\text{hyperx}} = T \cdot N_{\text{switch}} \label{eq:topo-hx-capacity} \end{equation}$$正确性约束：
- $C_{\text{hyperx}} = N_{\text{endpoint}}$（完整填满）
- $\forall i: S_i \geq 2$
- $L \in [1, 4]$，$T \geq 1$
- $T$ 同构——每个 switch 挂相同数量的 endpoint，不支持异构 $T_i$（详见 Alternatives Considered）
- 派生 $N_{\text{endpoint}} \mid N_{\text{chip}}$
枚举策略：以族参数 $(L, T, S)$ 遍历搜索空间，对每组合：
- 计算 $N_{\text{endpoint}} = T \cdot \prod S_i$
- 检查 $N_{\text{endpoint}} \mid N_{\text{chip}}$，不整除则丢弃
- 派生 $C_{\text{board}} = N_{\text{chip}} / N_{\text{endpoint}}$ $S$ 取字典序最小的规范形式避免重复（如 $[4, 2]$ 和 $[2, 4]$ 视为同构，只返回 $[2, 4]$）。
可用性警告（阈值为项目经验值，可配置）：
- $L = 4$ →
high-dimension - $\max(S) / \min(S) > 2$ →
asymmetric - $L = 1$ →
degenerate-to-single-switch - 派生 $C_{\text{board}} > C_{\text{board,max}}$ →
dense-pcb-impractical
层级归属：所有 switch → Tier 8 (Rack)。默认单 rack 单 pod。
Board 映射：1 endpoint ↔ 1 board。注意 $T$ 是"每交换机的 endpoint 数"，不等于 $C_{\text{board}}$——两者独立。
Ring
层级跨度：Tier 7 (Board)
设计原理：所有 board 首尾相连成环。无交换机。结构最简单但直径线性增长，只适用于小规模场景。Chip 间互联走 IntraBoardTopo，不在 Ring 族范围内——v1.3 移除了 v1.2 的"双模 scope"设计。
参数：无族专属参数；$N_{\text{endpoint}}$ 按枚举策略遍历。
枚举策略：与其他 Tier 7 叶子族统一——$N_{\text{endpoint}}$ 遍历 $N_{\text{chip}}$ 的所有因子（约束 $N_{\text{endpoint}} \geq 2$），派生 $C_{\text{board}} = N_{\text{chip}} / N_{\text{endpoint}}$。每个合法 $N_{\text{endpoint}}$ 产出一个独立枚举结果。
正确性约束：
- $N_{\text{endpoint}} \geq 2$
- $N_{\text{endpoint}} \in \text{divisors}(N_{\text{chip}})$
可用性警告（阈值为项目经验值，可配置）：
- $N_{\text{endpoint}} > 32$ →
high-diameter（环直径为 $\lfloor N/2 \rfloor$，通信延迟过大） - scope =
inter-rack→non-standard-scope - 派生 $C_{\text{board}} > C_{\text{board,max}}$ →
dense-pcb-impractical
层级归属：无交换机。Endpoint 直连，1 endpoint ↔ 1 board。默认单 rack 单 pod。
Full-Mesh
层级跨度：Tier 7 (Board)
设计原理：所有 board 两两直连。无交换机。直径 1 但链路数 $O(N^2)$，只适用于小规模 board 间互联。Chip 间互联走 IntraBoardTopo，不在 Full-mesh 族范围内。
参数：无族专属参数（同 Ring）。 枚举策略：同 Ring——$N_{\text{endpoint}}$ 遍历 $N_{\text{chip}}$ 的所有因子（≥2），派生 $C_{\text{board}}$。
正确性约束：
- $N_{\text{endpoint}} \geq 2$
- $N_{\text{endpoint}} \mid N_{\text{chip}}$
可用性警告（阈值为项目经验值，可配置）：
- $N_{\text{endpoint}} > 16$ →
link-explosion（链路数为 $N(N-1)/2$） - scope =
inter-rack→non-standard-scope - 派生 $C_{\text{board}} > C_{\text{board,max}}$ →
dense-pcb-impractical
层级归属：同 Ring。
Single-Switch
层级跨度：Tier 7 (Board) → Tier 8 (Rack)
设计原理：所有 endpoint 挂在同一台交换机上。最简单的交换网络，适用于小规模单 rack 场景。
参数：无（按 $N_{\text{endpoint}}$ 遍历可整除候选）。
正确性约束：
- $N_{\text{endpoint}} \geq 1$
- $N_{\text{endpoint}} \mid N_{\text{chip}}$
可用性警告（阈值为项目经验值，可配置）：
- $N_{\text{endpoint}} > 64$ →
radix-too-large - 派生 $C_{\text{board}} > C_{\text{board,max}}$ →
dense-pcb-impractical
层级归属：唯一 switch → Tier 8 (Rack)。1 endpoint ↔ 1 board。单 rack 单 pod。
IntraBoardTopo 机制
本质：IntraBoardTopo 是 Tier 6 层（Board 内 chip 间）互联的唯一表达通道。它与族拓扑（Tier 7+）正交独立。
适用条件：仅 $C_{\text{board}} > 1$ 时生效。$C_{\text{board}} = 1$ 时选择非 none 值必须报错——单芯片 board 内无需 chip 间连接。注意 $C_{\text{board}}$ 是派生输出，因此 IntraBoardTopo 的有效性以枚举结果的派生 $C_{\text{board}}$ 为判断依据，不是用户输入。
可选拓扑：
| 类型 | 语义 | 适用场景 |
|---|---|---|
none | 无 board 内连接 | $C_{\text{board}} = 1$ 或不需要 board 内互联 |
full-mesh | board 内 chip 两两直连 | NVLink 典型（DGX 8 GPU 全互联） |
ring | board 内 chip 环形连接 | 低端互联或特定硬件约束 |
torus | board 内 chip 组成小 torus | $C_{\text{board}}$ 为完美平方或立方时 |
@tbl-spec-topo-19 IntraBoardTopo 机制：类型，语义
torus 形状推导（按"立方 > 平方 > 报错"顺序判定）：
- 若 $C_{\text{board}}$ 是完美立方（存在整数 $m$ 使 $C_{\text{board}} = m^3$，且 $m \geq 2$）→ 3D torus $[m, m, m]$
- 否则若 $C_{\text{board}}$ 是完美平方（存在整数 $m$ 使 $C_{\text{board}} = m^2$，且 $m \geq 2$）→ 2D torus $[m, m]$
- 其他（既非立方亦非平方，如 $C_{\text{board}} = 2, 3, 6, 10$ 等）→ 报错，要求用户改用
intra_board_topo = ring或full-mesh
特例：同时满足立方和平方（如 $C_{\text{board}} = 64 = 4^3 = 8^2$）按顺序取立方 3D [4, 4, 4]——与 §Torus 族 "完美对称性" 设计原理一致。
与族拓扑的关系：族（如 Fat-Tree）产出 endpoint 间链路（Tier 7+）；框架对每个 board 内部的 $C_{\text{board}}$ 个 chip 按 IntraBoardTopo 选项补充 Tier 6 链路。Ring/Full-mesh 族不再有 intra-board scope——chip 间环或全互联统一用 IntraBoardTopo=ring/full-mesh 表达。
设计理由——为什么 IntraBoardTopo 是框架职责而非族职责：Board 内互联（Tier 6）是封装层面的决策，取决于硬件平台（NVLink 版本、PCB 布线），与跨 board 的网络拓扑（Tier 7+）无关。fat-tree 不需要知道 DGX board 内是 full-mesh 还是 ring。将两者解耦使得任何族都可以与任何 board 内拓扑自由组合。
Scope 与层级适用性
scope 是用户输入。每个族声明自己适用的 scope 列表（v1.3 起 scope 只含 intra-rack 和 inter-rack，intra-board 由 IntraBoardTopo 表达，不再作为 scope）：
| 族 | 适用 scope | 理由 |
|---|---|---|
| fat-tree (PGFT) | intra-rack, inter-rack | Tier 7-9，从单 rack 到多 pod |
| dragonfly / dragonfly+ | inter-rack | Tier 7-9，设计用于大规模跨 rack |
| torus | intra-rack, inter-rack | Tier 6-8，小到单 rack，大到 TPU Pod |
| hypercube | intra-rack | Tier 6-7，教学用，不适合大规模 |
| hyperx | inter-rack | Tier 7-8，交换机互联 |
| ring / full-mesh | intra-rack | Tier 7，小规模 rack 内（v1.3 起仅 board 间互联，chip 间走 IntraBoardTopo） |
| single-switch | intra-rack | Tier 7-8，单 rack |
@tbl-spec-topo-20 Scope 与层级适用性：族，适用 scope
scope 不匹配处理：不硬拒绝，返回结果但标 edge-case + non-standard-scope 警告。用户可以在 UI 中展开查看。
物理层级产出
族的生成结果除了网络图外，还必须产出物理层级分组信息——即 chip → board → rack → pod 的嵌套关系。这个信息用于：
- 3D 可视化：Scene3D 按 pod → rack → board → chip 分层渲染
- 一致性保证：网络拓扑中 rack 级交换机连接的 board 确实在同一个物理 rack 中
物理层级产出的核心原则：
- 族决定分组规则：fat-tree 按 ToR 下挂关系分 rack；torus 按坐标切分分 board；dragonfly 按 group 分 rack
- 框架验证一致性：见下文 invariant 清单
- 层级归属不可跨级：rack 级交换机只能归属 Tier 8，不能声称在 Tier 7 或 Tier 9
拓扑元数据（每个枚举结果都附带）：
为支持下游路由对比、性能仿真、可视化排序，每个枚举结果除了网络图和物理分组外，还产出可计算的拓扑指标：
| 指标 | 计算方法 | 用途 |
|---|---|---|
diameter | 网络图最长最短路径（hop 数） | 路由延迟分析、规模合理性判断 |
bisection_bandwidth | 等分二分带宽（最小切割 × 单链路带宽） | 全网吞吐建模 |
link_count | 总链路数 | 成本估算、布线复杂度 |
switch_count | 总交换机数 | 成本估算 |
path_diversity | 任意两端点间最大独立路径数（最小 vertex-disjoint path count over all pairs；可达对必 ≥ 1，含 multi-edge 时按重边权重计算） | 路由策略（ECMP / AR）选型 |
derived_chips_per_board | 派生 $C_{\text{board}}$ 值 | 硬件设计反推 |
family_attrs | 族专属字段字典——Fat-Tree: {w_levels, p_levels, k, layers, osr}；Torus: {dimension_sizes, board_shape}；Dragonfly: {a, p, h, g}；Dragonfly+: {a, p, s, g}；HyperX: {L, T, S}；Hypercube: {n}；Ring/Full-mesh/Single-switch: {} | 下游路由模块的 attrs schema 输入（如 D-mod-k 路由读 w_levels/p_levels） |
@tbl-spec-topo-20b 拓扑元数据
这些指标在生成时一次性计算，避免下游消费方各自重算。
框架后处理的一致性 invariant（在阶段三末尾全部校验，违反任何一条直接报错）：
- Chip 覆盖完整性：$\bigcup_{b \in \text{boards}} \text{chips}(b) = \{0, 1, ..., N_{\text{chip}} - 1\}$，无遗漏、无重复
- Board 大小一致：$\forall b \in \text{boards}: |\text{chips}(b)| = C_{\text{board}}$（派生 $C_{\text{board}}$ 值）
- Rack 非空：$\forall r \in \text{racks}: |\text{boards}(r)| \geq 1$
- Pod 非空：$\forall p \in \text{pods}: |\text{racks}(p)| \geq 1$
- Switch 层级归属合法：
switch.tier ∈ {Tier 8 (Rack), Tier 9 (Pod), Tier 9+ (Datacenter)}；Tier 6/7 不允许出现 switch - Rack 级 switch 包含一致性：对每条
endpoint ↔ rack_switch链路，endpoint 所属 board 必须在 rack_switch 所属 rack 内 - Pod 级 switch 包含一致性：对每条
rack_switch ↔ pod_switch链路，rack_switch 所属 rack 必须在 pod_switch 所属 pod 内 - Link multiplicity 合理：同一对端点间的并行链路数 $\leq \min(\text{chip\_radix}, \text{switch.port\_count})$（对 Tier 6 叶子族，$N \leq \text{chip\_radix}$）
- 网络连通性：去除 multi-edge 后的简单图必须是连通的（无孤立 chip/board/rack）
- Endpoint 唯一性：每个 chip 在 boards/network 中至少出现一次且不超过其 chip_radix 次（不允许"未连接"的孤立 chip）
@tbl-spec-topo-20a 框架后处理 invariant 清单
硬件设计反推
核心设计哲学：本模块支持硬件设计未冻结的早期场景——$C_{\text{board}}$ 是输出不是输入。
与业界工具的对比
业界拓扑生成器（BookSim、SST/Merlin、CODES、ASTRA-sim）都假设用户已知硬件——先填硬件参数（每 board chip 数、机柜数），再选拓扑。这适合部署阶段——硬件采购已定，只在已知硬件上选互联方案。
本模块覆盖设计阶段——用户在 PCB 设计、机柜规划尚未冻结时，用拓扑选型驱动硬件设计。$C_{\text{board}}$ 是各拓扑方案对硬件的"诉求"，用户从可行集中挑出综合最优的（含拓扑性能、硬件复杂度、$C_{\text{board}}$ 实现成本等多目标考量）。
派生方向
| 族叶子层级 | 派生公式 |
|---|---|
| Tier 7 (Board) | 族参数（如 Fat-Tree 的 $k, layers, osr$）决定 $N_{\text{endpoint}}$；$C_{\text{board}} = N_{\text{chip}} / N_{\text{endpoint}}$ |
| Tier 6 (Chip) | 族 board_shape 参数 $B_d$ 决定 $C_{\text{board}} = \prod B_d$；该族的 $N_{\text{endpoint}} = N_{\text{chip}}$ |
软约束：$C_{\text{board,max}}$
PCB 物理上有 chip 装载上限。用户通过 chips_per_board_max 参数（默认 16，基于业界 dense PCIe carrier 经验上限）告知生成器：派生 $C_{\text{board}}$ 超此值的结果触发 dense-pcb-impractical warning，但不硬拒绝——用户可调高该值看完整结果集。
典型用户流程
- 输入 $N_{\text{chip}} = 32$、scope =
intra-rack - 选 Fat-Tree 族 → enumerate 返回多个候选：
- $k = 4, L = 2$：派生 $C_{\text{board}} = 8$（每 PCB 8 chip）
- $k = 8, L = 2$：派生 $C_{\text{board}} = 4$
- $k = 16, L = 2$：派生 $C_{\text{board}} = 2$
- 用户基于其他考量（性能 / 成本 / PCB 复杂度）选其一
- 该 $C_{\text{board}}$ 值即为硬件设计输入——PCB 工程师按此设计 board
设计理由
- $C_{\text{board}}$ 是物理 PCB 设计决定的，但拓扑层面的"诉求"先于硬件实现——拓扑算出 $C_{\text{board}}=8$，PCB 工程师再决定怎么布线
- 让生成器内部遍历 $C_{\text{board}}$ 等于把"选硬件"和"选拓扑"两件事混在一起，决策粒度不一致
- 翻转后接口更干净：用户输入只剩 $N_{\text{chip}}$ + scope + 物理上限，生成器产出"拓扑 + 派生硬件诉求"的二元包
Alternatives Considered
endpoint 展开由族自行完成（拒绝）
方案：每个族直接产出 chip 级链路，框架不做 endpoint→chip 展开。
拒绝理由：对叶子在 Tier 7 的族（fat-tree、dragonfly 等），展开逻辑完全相同——每个 endpoint 替换为 $C_{\text{board}}$ 个 chip。让每个族重复实现这个逻辑增加了维护成本，且容易出现不一致。
IntraBoardTopo 由族负责（拒绝）
方案：族在 generate 内部处理 board 内连接。
拒绝理由：Board 内连接（Tier 6）与跨 board 拓扑（Tier 7+）在不同层级，正交独立。让族处理 board 内连接意味着每个族都要感知 $C_{\text{board}}$ 和 IntraBoardTopo 类型，增加了族的实现复杂度。框架统一处理保证了任意族 × 任意 board 内拓扑的自由组合。
scope 不匹配时硬拒绝（拒绝）
方案：用户选择 inter-rack 时，ring / full-mesh 不出现在枚举结果中。
拒绝理由：作为探索工具，不应限制用户查看"非标准但数学合法"的配置。硬拒绝会让用户困惑于"为什么这个族在这个 scope 下没有结果"。软标记 + UI 折叠是更好的平衡。
统一所有族的 endpoint 层级（拒绝）
方案：强制所有族的 endpoint 都在 Tier 7 (Board)，torus / hypercube 也以 board 为单位生成。
拒绝理由：Torus 的坐标映射和 Hypercube 的二进制地址本质上是 chip 级的操作。强制 board 级会丢失族的结构语义——torus 的 [8,8] shape 描述的是 64 个 chip 的 2D 排列，不是 board 的排列。
产品锚点硬编码（拒绝）
方案：枚举时绑定具体厂商产品参数（如 Mellanox QM9700 radix=64）。
拒绝理由：与"探索工具"定位冲突。硬绑定产品规格限制了研究非主流配置的自由度，且产品更新快难以维护。
Fat-Tree 实现为 generic Clos（拒绝）
方案：Fat-Tree 族保持抽象的 Spine-Leaf 结构，不严格要求 PGFT 的层级对称性。
拒绝理由：项目下游路由模块（v1.3.1）已实现 D-mod-k 作为 Fat-Tree 专属路由，要求拓扑必须是 PGFT 或其子集（含显式 $w_i, p_i$ 参数）。Generic Clos 拓扑无法支持 D-mod-k，会造成上下游 spec 接口断裂。
HyperX $T$ 异构（拒绝）
方案：HyperX 允许每个 switch 挂不同数量的 endpoint，处理 $N_{\text{chip}}$ 不能被 $\prod S_i$ 整除的场景。
拒绝理由：(a) 异构 $T$ 引入背包式参数空间，enumerate 爆炸；(b) 业界主流（Cray Slingshot）都用同构 $T$，避免路由不对称；(c) 派生 $C_{\text{board}}$ 模式下，整除问题可通过调 $C_{\text{board}}$ 解决，无需异构 $T$。如未来真需要异构 $T$，作为新族 hyperx-heterogeneous 单独实现。
Dragonfly 强制 $g = ah + 1$（拒绝）
方案：保持 v1.2 的"balanced Dragonfly 唯一合法形式"，$g$ 等号强制。
拒绝理由：实际部署（Cray Cascade XC 系列）的 $g$ 通常远小于 $ah + 1$（按机柜数定）。Kim 2008 推导的 $g_{\max} = ah + 1$ 给的是性能最优解，不是合法性边界。强制等号会丢失大量真实部署规模（如 $N = 64$ 找不到合法解）。
Partial Torus / Mesh Fallback（拒绝）
方案：当 $\prod S_d \ne N_{\text{chip}}$ 时，截断 torus 边界或退化为 mesh（无 wraparound）。
拒绝理由：Torus 的对称性和带宽保证依赖完整环形结构；缺损 torus 导致直径分析不再成立、路由从确定性变为自适应、带宽不均匀。业界也不部署不完整 torus。如真有此需求，作为独立 mesh 族实现，不混入 torus。
多平面 / 多实例族（拒绝）
方案：spec 引入 "族实例叠加" 概念，同一组 chip 上可同时运行多种连接结构（如 2 plane × Fat-Tree）。
拒绝理由：chip 间通信粒度上，多平面与"chip 间多 link"语义等价（路径数、带宽、延迟分布相同），可用 multi-edge NetworkGraph 直接表达，不必引入新族级抽象。如未来需要建模故障容错（单平面失效）才考虑扩展。
Drawbacks & Risks
| 风险 | 影响 | 缓解 |
|---|---|---|
| 可用性警告规则主观性强 | 合理配置可能被误标 edge-case | 警告阈值可配置；提供"显示全部"选项 |
| Torus 的 endpoint=chip 特殊性增加框架复杂度 | 族作者需理解两种 endpoint 语义 | 框架文档明确标注，提供默认 helper |
| Torus 强制完整填满限制灵活性 | 非标准芯片数（如 30）无法用 torus | 枚举阶段提示用户调整 numChips 或选其他族 |
| 前端生成大规模拓扑可能慢 | 1024+ endpoint 时 UI 卡顿 | enumerate 限制返回条数，generate 为纯计算可优化 |
| scope 分档主观 | 特定场景推荐不准 | 用户可手动切换 scope |
chip_radix 派生 link 数引入歧义 | 同族不同 link 配置（如 chip_radix=1 vs 8）路由策略不一定兼容 | 族 generator 必须在元数据中显式声明每 chip 的 link 数；路由策略读元数据决定是否兼容 |
| 50 条上限可能截断有用结果 | 大 $N_{\text{chip}}$（如 1024）下合法 fat-tree 组合 > 50 | 按 status 优先级排序，先返回 recommended，edge-case 排后；UI 提供"放宽上限"开关 |
| $C_{\text{board}}$ 翻转后旧 v1.2 调用方需迁移 | breaking change，调用方需要重写 | spec v1.3 标注 breaking；提供迁移示例：旧 enumerate(N_chip=32, C_board=8, ...) → 新 enumerate(EnumerationContext(n_chip=32, scope=..., chips_per_board_max=...)) + 在结果集中按 derived $C_{\text{board}}$ 过滤 |
| 多 warning 叠加 UI 展示复杂度 | warning 数组可能很长（如同时触发 3 条） | UI 按 severity 排序展示，默认折叠次要 warning |
@tbl-spec-topo-21 风险与缓解措施
Success Criteria
层级一致性
| 场景 | 指标 | 目标 |
|---|---|---|
| 任意族生成结果 | 后端 graph_builder 解析无报错 | 100% |
| 物理层级产出 | board 总 chip 数 = $N_{\text{chip}}$ | 所有族满足 |
| 层级归属 | rack 级 switch 只出现在 rack 容器内 | 所有含 switch 的族满足 |
| 3D 渲染 | 保存 + 跳转后 Scene3D 正确渲染 | 所有 recommended 配置通过 |
@tbl-spec-topo-22 验收标准
约束正确性
每条用例的判定语义为 "warnings 包含 X"（CRIT-5 决议：warnings 数组可叠加）：
| 场景 | 预期 |
|---|---|
| fat-tree (PGFT): $N_{\text{chip}} = 32$, 2-layer | 至少 1 个 recommended；每个结果带派生 $C_{\text{board}}$（如 k=4→$C_{\text{board}}=8$，k=8→$C_{\text{board}}=4$，k=16→$C_{\text{board}}=2$） |
| fat-tree (PGFT): $N_{\text{chip}} = 32$, 3-layer | 全部 edge-case，warnings 数组包含 over-engineered |
| fat-tree (PGFT): $k = 4$, $osr = 2$ | 该参数组合丢弃（公式 $\eqref{eq:topo-ft-port-split}$ 无整数解） |
| dragonfly: $N_{\text{chip}} = 32$ | 所有结果 edge-case，warnings 包含 degenerate；可同时含 low-utilization |
| dragonfly: $N_{\text{chip}} = 64$, $a = 4$, $p = 2$, $h = 2$, $g \in [2, 9]$ | 至少 1 个 recommended（$g = 8$ 时 $C = 64$）；$g < 9$ 标 non-balanced-global-link |
| dragonfly+: $N_{\text{chip}} = 32$ | 全部 edge-case，warnings 包含 over-engineered |
| torus: $N_{\text{chip}} = 23$ | 枚举返回空数组（23 为质数，无 $\prod S_d = 23, S_d \geq 2$ 的多维分解；原 v1.3.0 写 N=30 系笔误——30=5×6=2×15 实际有合法 2D 分解，已在 v1.3.1 patch 修正） |
| torus: $N_{\text{chip}} = 32$ | 枚举返回多个结果（shape × board_shape 各组合独立返回，含 $C_{\text{board}} \in \{1, 2, 4, 8, 16\}$ 多档） |
| hypercube: $N_{\text{chip}} = 32$ | 1 个结果（$n = 5$），warnings 包含 research-only |
| hypercube: $N_{\text{chip}} = 30$ | 枚举返回空（非 $2^n$） |
| hyperx: $N_{\text{chip}} = 64$ | 多个结果（$L \in \{1,2,3,4\}, T, S$ 各组合），含 $L = 1$ 标 degenerate-to-single-switch |
| hyperx: $N_{\text{chip}} = 97$ | 枚举返回空数组（97 为质数，无合法 $(L, T, S)$ 满足 $T \cdot \prod S_i = 97$ 且 $S_i \geq 2, L \geq 1, T \geq 1$） |
ring: $N_{\text{chip}} = 16$, scope = inter-rack | 所有结果 edge-case，warnings 包含 non-standard-scope |
| ring: $N_{\text{chip}} = 64$, $C_{\text{board}} = 1$（派生） | warnings 包含 high-diameter（$N_{\text{endpoint}} = 64 > 32$） |
| full-mesh: $N_{\text{chip}} = 32$，派生 $N_{\text{endpoint}} = 32$ | warnings 包含 link-explosion（32 > 16） |
| single-switch: $N_{\text{chip}} = 64$，派生 $N_{\text{endpoint}} = 64$ | warnings 包含 radix-too-large |
$C_{\text{board}} = 1$, intra_board_topo = full-mesh | 报错（IntraBoardTopo 与单 chip board 不兼容） |
$C_{\text{board}} = 4$, intra_board_topo = torus, single-switch | 成功；board 内 2×2 torus |
$C_{\text{board}} = 64$, intra_board_topo = torus | board 内 4×4×4 torus（立方优先于 8×8 平方） |
| 派生 $C_{\text{board}} = 32 > C_{\text{board,max}} = 16$ | warnings 包含 dense-pcb-impractical |
@tbl-spec-topo-23 约束正确性：场景，预期
性能
| 场景 | 目标 |
|---|---|
enumerate(1024) 单族 | $\leq$ 200ms |
generate() 1024 endpoint | $\leq$ 100ms |
| 单族 enumerate 最多返回 | 50 条 |
@tbl-spec-topo-24 性能：场景，目标
Future Possibilities
多层组合拓扑（高优先级）
支持同时配置多个层级的拓扑——例如 Tier 8-9 用 fat-tree，Tier 7-8 用 dragonfly，Tier 6 用 full-mesh。生成器一次性产出完整多层结构。这是 Tier 6-9 层级模型的自然延伸。
非均匀 PGFT 变体（中优先级）
当前 Fat-Tree 实现限定 k-ary n-tree 形态（$w_i$ 均匀、$p_i = 1$）。未来扩展支持非均匀 $w_i$ / 非 1 $p_i$ 的完整 PGFT 参数空间，覆盖更多业界 Clos 变体（如 oversubscribed 上层、非对称 spine）。
探索模式增强（中优先级）
跨族混合探索，支持"对比 fat-tree vs torus vs dragonfly 在同规模下的表现"，按拓扑指标（直径、等分带宽、链路数、成本）排序。
自动寻优（低优先级）
给定目标函数（最大化等分带宽 / 最小化直径 / 最小化成本），自动搜索最优参数组合。需要先定义成本模型和性能目标函数。
多平面冗余建模（低优先级）
当 chip 有多 c2c port 且工程上需要 multi-plane 冗余（单 plane 失效仍保留部分带宽）时，spec 当前只表达"chip 间多 link"语义；未来如需建模故障容错，扩展 NetworkGraph 增加 plane 标记字段。
Implementation Notes
本节在实现完成后补充，记录 spec 与实际实现的偏差。