五层协议栈，每层开放独立扩展点
灵衢协议栈分层实现，每层开放独立扩展点。拥塞控制、流控、路由和链路行为均可独立替换，同一架构适用于多类高性能互连实验场景。点击左侧查看各层详情。
功能层
事务层
传输层
网络层
数据链路层
功能层
功能层负责把上层通信语义映射到可执行的网络事务。它同时覆盖 Load/Store 与 URMA 两类接口，并通过 Jetty 把应用侧意图交给下层传输与调度逻辑。
多线程并发 · 逐线程独立配置
控制器自动转换为事务操作
大消息自动切分 · 乱序确认
通过 Jetty 接口提交事务操作
Load/Store 接口
- 用同步内存语义描述远端读写，由控制器翻译成事务流
- 线程级配置可以独立控制路径策略与发送方式
URMA 接口
- 用异步接口表达 Write / Read / Send 等操作
- 适合研究消息与内存访问混合场景
Jetty 通信码头
- 多对多：一个端点同时管理多个通信对
- 单对单：固定绑定单一对端，便于复现实验
扩展方式
- 新增功能类型只需实现对应上层接口并接入 Jetty
- 消息切分与调度逻辑可独立替换
事务层
事务层把不同编程模型统一到一组明确的事务语义上。它的价值在于让上层接口差异不会直接污染下层传输与可靠性设计。
ROL 可靠 · 下层保序 · 单路径
UNO 无保序 · 最低开销
RO 松弛 — 同类有序，不同类可乱序
SO 严格 — 按提交顺序执行
Read 请求远端回传数据
Send 双边消息传递
服务模式
- ROI：可靠交付 + 发起端顺序约束，同时允许路径层面并发
- ROL / UNO：分别面向下层保序与最低约束的两类实验场景
事务序 (TEO/TCO)
- 执行顺序和完成顺序被显式建模，便于研究语义差异带来的代价
- 三级有序性（NO/RO/SO）覆盖从全乱序到全严格的实验需求
事务类型
- Write、Read、Send 构成统一事务集合，覆盖常见远端访问模式
- 大事务会被自动拆分后重组交付，语义与数据面保持一致
扩展方式
- 新增服务模式只需在事务层注册，下层传输和可靠性设计可复用
- 事务切片策略可独立调整，适配不同 MTU 和多路径场景
传输层
传输层提供端到端数据传输的核心能力：可靠交付、多路径均衡、拥塞控制和连接管理。各项能力可独立配置，方便对比不同策略组合对性能的影响。
传输服务
- 基于报文序号的可靠传输，支持超时重传与自动退避
- 可选旁路（bypass）模式，便于对比有无传输保障的性能差异
负载均衡
- 原生多路径，数据在多条等价路径上同时传输
- 逐包均衡基于虚拟随机端口实现，接收端自动重排恢复原序
拥塞控制
- 内置 CAQM 算法，覆盖发送限速、交换机标记、接收反馈完整链路
- 预留标准算法接入位置，新策略按接口规范实现即可替换
连接管理
- 每条传输连接独立维护状态，并发连接互不干扰
- 连接可分组统一调度，配合多路径协同工作
网络层
网络层承担寻址、路由、调度与拥塞标记，支持 ECMP、自适应路由和多种拥塞反馈策略。
报文格式与地址
- 同时支持 IPv4 与 16-bit CNA 两种地址表达
- CNA↔IP 转换和 Primary / Port CNA 双地址让跨域实验易于建模
路由查找
- 路径 Cost 建模使最短路径与绕路策略可直接对比
- 支持 ECMP Hash 与按端口负载的自适应选路
服务质量 (QoS)
- 服务等级到虚通道的映射让业务分类与调度策略解耦
- 严格优先级与加权轮询两种调度可直接对比隔离性与公平性
拥塞标记与缓冲区
- 拥塞标记与下游反馈链路衔接，形成端到端拥塞感知
- 动态阈值与暂停/恢复水位共同决定背压触发条件
数据链路层
数据链路层负责逐跳可靠传输、虚通道隔离与流量控制。信用流控和优先级流控两大机制均已建模，可直接对比不同策略的队列行为。
报文收发
- 以 Flit 为基本单位；CRC / Non-CRC 模式让可靠性与时延权衡可显式比较
- 点到点重传 把逐跳纠错与端到端重传分开建模
虚通道 (VL)
- 每链路最多 16 个 VL，SP 与 DWRR 可直接对比隔离性与公平性
- 通过服务等级映射把业务语义绑定到具体虚通道
信用流控 (CBFC)
- 独占 适合严格隔离场景；共享 允许在预留之上复用信用池
- Credit Ack 逐包归还信用，接收端缓冲状态可细粒度感知
优先级流控 (PFC)
- 固定阈值 便于控制变量；动态阈值 研究缓冲占用对暂停策略的影响
- 与上层缓冲区准入逻辑直接联动，形成完整背压信号链路
以上分层首先服务于灵衢协议研究，模块化扩展点同样适用于其他高性能互连场景的算法建模。
用仿真可以研究什么
6 个典型实验方向，每一项在仓库中都有对应的预置场景和可直接修改的参数入口。
包喷洒 vs 流哈希
在 Fat-tree 拓扑下对比逐包随机喷洒与流级 ECMP Hash，观察各路径的负载分布、队列深度与整体吞吐差异。
拥塞控制参数扫描
扫描 C-AQM 的 ECN 标记门限 T 与动态阈值因子 α，量化参数组合对队列深度、吞吐与 P99 时延的影响规律。
集合通信拓扑对比
在 Fat-tree 与 Ring 拓扑下运行相同的 AllReduce 工作负载，对比完成时间、链路利用率与瓶颈位置的差异。
CBFC vs PFC 流控对比
在相同拥塞场景下比较信用流控与优先级流控，量化 HOL 阻塞对低优先级流吞吐与时延的影响程度。
链路故障与传输韧性
向链路注入丢包、闪断或降速，观察端到端重传、RTO 触发与流量绕行的恢复过程，量化不同可靠性配置的代价。
TPG 多路径带宽聚合
通过 TP Channel Group 把多条并行路径纳入同一传输对象，对比不同喷洒策略下的有效带宽、乱序率与重排开销。
14 个预置仿真场景
仓库内置 14 个预配置场景，覆盖从双节点机制验证到 32 节点数据中心实验。可以先跑通确认环境，再替换参数、路由策略或拓扑结构。
双节点
2 个节点直连，1 条链路，最小可运行的点对点配置
32 节点 Clos
2 层 Spine-Leaf，4 Spine 全连 4 Leaf，每 Leaf 下挂 8 台 Host，共 32 节点
4×4 FullMesh
16 个 Host 排成 4×4 网格，同行同列节点两两直连，无交换机
自定义拓扑
用 Python 脚本自定义节点、链路和路由，自动生成整套 CSV 配置
拓扑定义 → 流量生成 → 仿真执行 → 结果解析
仓库内置工具链将上述四步串成可复用的实验路径，减少手工拼接配置文件的工作。
g = Graph()
g.add_nodes("0..31")
g.build()
定义拓扑
用 Python 描述节点、
链路和路由结构
导出配置
自动生成拓扑图
及 node/topology/routing CSV
编排流量
覆盖 All-Reduce / All-to-All
RDMA 读写和自定义 DAG
解析结果
输出 task_statistics.csv
与逐端口 throughput.csv
任意拓扑生成
用代码描述拓扑，自动生成节点与链路配置，无需手写 CSV。
流量模式编排
集合通信与 RDMA 负载统一编排，实验输入格式一致，可复现、可对比。
Trace 结果解析
原始 trace 自动收敛为任务统计和端口吞吐摘要，直接用于跨实验对比。
五步跑通第一个仿真
# 克隆项目并初始化子模块 $ git clone https://gitcode.com/open-usim/ns-3-ub.git $ cd ns-3-ub $ git submodule update --init --recursive # 安装 Python 工具依赖 $ pip install -r scratch/ns-3-ub-tools/requirements.txt # 配置并构建 $ ./ns3 configure $ ./ns3 build # 运行第一个仿真 $ ./ns3 run 'scratch/ub-quick-example \ --case-path=scratch/2nodes_single-tp' [00:00:01] Run case: scratch/2nodes_single-tp [00:00:01] Simulator finished! [00:00:01] Start Parse Trace File. 处理完成 → output/task_statistics.csv 处理完成 → output/throughput.csv
更完整的命令说明见 QUICK_START.md · 支持 Linux 与 Windows WSL · 需要 g++≥10 / clang++≥11 · Python≥3.8 · CMake≥3.13
专为网络仿真定制的 Agent Skills
Agent Skills 覆盖环境检查、实验规格设计、脚本生成执行到结果解读的完整流程，让 Cursor、Claude Code、Codex 等工具在这个项目里更准确地执行每一步。
仓库就绪
规格设计
生成执行
结果解读
./ns3 configure && ./ns3 build，确认执行吗？
build/ 和 cmake-cache/ 不存在，需要先构建（需要几分钟）。是否执行 ./ns3 configure && ./ns3 build？Topology: 双节点 (2nodes_cbfc)
Workload: 单流 100% line-rate
Network: FlowControl=CBFC_Exclusive
Observability: queue_depth + latency
scratch/20260328-cbfc-pfc/experiment-spec.md，准备生成执行。./ns3 run 中…4 个 skill 串联成闭环流程，从环境检查到结果分析全程有据可查；规范参数对齐之后，工具的建议也更贴合实验场景。查看 Agent Skills 专题页 →