查看本机可用的仿真引擎，以及不可用的引擎缺什么。

引擎不可用时不会报错，而是如实标注——避免用户以为是自己用错了。

列出场景预设。预设只提供场景骨架，具体参数由 sw_plan 协商决定。

参数

group : 只看某一组（干扰场景 / 测量干扰 / 大站间距 / 移动性 / 传播条件 / 多小区干扰 / 基线 / 射线追踪 / 室内与专网）。不给则全给。

把用户的仿真意图变成一份配置提案，并给出该和用户确认哪几件事。

参数

intent : 用户的原话，例如"验证一个 CSI 压缩的想法，单小区 64T4R" preset : 场景骨架名；不给则按意图自动挑 overrides : 用户已经明确表态的参数 max_questions : 最多提几个问题（建议 3~6）

返回里最重要的是 questions —— 每条都带 why，说明这个选择为什么会改变 结论。请把 why 转述给用户，不要只列选项值。

另外 also_configurable 只给参数名不展开，用来告诉用户"还能调这些"。

用户若无明显偏好，直接用默认值调 sw_generate 即可，不必逐条确认。

差分修正一份提案——用户只说改什么，不必重述整个需求。

overrides 改仿真参数，例如用户说"信噪比降到 5 dB"： sw_revise(draft_id, overrides={"snr_range_dB": [0, 5]})

design 记录实验设计层的回答，例如用户说"跟 Type II 码本比，看 NMSE"： sw_revise(draft_id, design={"baseline": "3GPP Type II 码本", "metric": "NMSE 与频谱效率损失"})

design 不影响任何仿真参数，但会写进计划书——三个月后回看时， 这部分比参数值有用得多。

列出射线追踪可用的场景（真实建筑几何）。

内置场景（慕尼黑、巴黎凯旋门、佛罗伦萨、旧金山）开箱即用； 中国城市场景（北京中关村、上海陆家嘴、深圳福田、广州天河、杭州钱江、 重庆解放碑）首次使用时会自动准备资产，需要几秒。

生成信道数据集，返回句柄与统计摘要（不返回数据本身）。

两种用法：

• 协商过：只传 draft_id

• 用户说"随便，默认就行"：直接传 intent，跳过协商

返回里的 auto_decided 列出了替用户做的决定，请转述给用户， 这样他事后想改也知道改什么。

prereg_id 是 sw_lock_analysis 返回的预注册句柄。传了它，主指标与基线会 随数据存档，之后 sw_compare_results 能判断用的指标是不是事先定的那个。 只能在生成前绑定——事后补绑没有意义。

workers 默认 "auto"：按配置预估耗时决定要不要起多进程。多小区大带宽的 配置能快 3 倍以上；轻配置起进程反而更慢，会自动走串行。 并行时各块用不同 seed，结果与串行统计等价但逐样本不同（摘要里会写明）。

collect_ssb=False 关掉每小区 SSB RSRP/SINR 的计算，多小区场景省约 30% （交错重测中位数 3456 -> 2475 ms/样本，基准自身轮间波动 11.9%）。 代价是 Dataset.ssb 为空——小区选择、切换、波束管理类课题需要它，别乱关。 默认 None = 保留，不静默减少数据。

按需生成取货代码——返回可直接运行的 Python，不是数据。

want 可以写自然语言："信道"、"信道 + PMI + SRS RSRP"、"我还想看时延功率谱"。 不写则只给信道。

同一个数据集可以反复取货要不同的测量量，不必重跑仿真。

查看已生成数据集的维度、统计分布和可用字段。

列出本机已生成的数据集。

可信度体检：这批信道能不能拿来下结论。

三类检查：对标 3GPP 38.901 的路损与时延扩展；对标物理定律（时频能量守恒、 谱效不超容量上界、预编码方案的性能排序、SISO 退化到香农公式）； 统计层面（蒙特卡洛是否收敛、信噪比分布是否够宽）。

蒙特卡洛仿真前建议先跑一次。 结论建立在信道之上， passed 为 false 时先修配置再做实验。

算谱效：预编码 → 逐层 SINR → 频谱效率，并横向对比多种预编码方案。

这是蒙特卡洛仿真最常用的评价链路。返回各方案的谱效均值、95% 置信区间 和收敛判断——不收敛时方案间的差异可能只是噪声，会明确标出。

参数

methods : 默认对比 ["svd", "svd_wideband", "type1", "dft"]。 SVD 是理论上界，Type I 是 3GPP 码本，DFT 是单层波束。 用户自研方案应当和这几个在同一批信道上比。 use_estimated_csi : True 时用估计信道计算预编码、用理想信道评估性能， 得到的是"CSI 有误差时的实际代价"——CSI 反馈类课题的核心对比。 receiver : mmse（默认）/ zf / mrc。

按 3GPP TR 38.901 §7.8 的口径算校准量。

这是业界判断"信道生成得对不对"的标准做法：不看曲线好不好看，而是把标准 规定的几个统计量按规定口径算出来，跟各公司提交给 3GPP 的参考曲线对。

出的量（括号内是标准里的条款与指标号）：

• 耦合损耗 CDF（§7.8.1 指标1）—— 串联检验路损模型 + 天线方向图 + 小区选择

• 几何量 CDF，含噪与不含噪两条（§7.8.1 指标2 / §7.8.2 指标2）

• 时延扩展与角度扩展 ASD/ASA/ZSD/ZSA（§7.8.2 指标3，Annex A.1 圆周定义）

• PRB 奇异值：最大、次大、比值三条 CDF，10log10 尺度（§7.8.2 指标4）

参考曲线在 3GPP 文稿 R1-165974（大尺度）、R1-165975（全校准）、 R1-1909704（InF）里。本工具只出数不判决，判决在 sw_gate。 不适用的项会说明原因（例如 CDL 的时延角度是查表固定值，CDF 是退化的）。

评审门：拦住站不住的结论。

stage="channel"（门 1）—— 生成之后、做实验之前跑。把可信度体检的 结果翻译成门禁语言：硬性检查不通过就是拦截项，不修不许往下走。

门 2（比较公平）与门 3（结论站得住）在 sw_compare_arms 里一次跑完， 因为它们需要两个方案的逐样本结果。

在同一批信道上跑两个方案，做配对比较，并连过门 2、门 3。

这是下结论前的最后一道关。它做四件普通的"比均值"做不到的事：

1. 配对 —— 两臂共用同一批信道实例，共同的路损/撒点/衰落起伏被差分 抵消，剩下的才是方案本身的差别。配对设计所需样本数常比非配对少一个数量级。

2. 公平性检查（门 2） —— 配置漂移、CSI 口径不一致（一边理想一边估计 就是让自己的方法偷看答案）会被直接拦截。

3. 统计检验（门 3） —— 配对 t 检验 + Wilcoxon 符号秩双保险，95% 置信 区间跨零就拦，单个样本贡献过半也拦。

4. 一句可直接写进报告的结论 —— 过不了门时它会明说结论不成立及原因。

method_*：svd / svd_wideband / type1 / dft / mrt / identity。 csi_*：ideal 用理想信道预编码，estimated 用估计信道。 snr_db 不给时用数据集逐样本自身的 SINR（各用户真实工作点）。

样本数该定多少 —— 算出来的，不是问用户的。

蒙特卡洛跑多少次，取决于想检出多大的效应和逐样本差值有多离散::

N ≥ ( (1.96 + 0.84) · σ_d / Δ )^2

三种用法：

• 给 std_diff 和 expected_effect → 返回需要的样本数；

• 给 std_diff 和 n_current → 返回这个实验最小能检出多大效应。 这个数比样本数更该先看：它比期望增益还大时，实验无论跑出什么结果 都不足以下结论；

• 什么都不给 → 返回试点流程（先跑 20 个样本量方差）。

std_diff 从 sw_compare_arms 的 paired.std_diff 取。

结论模板里还空着哪些槽 —— 决定该主动问用户什么。

一次蒙特卡洛仿真的产出说到底就是一句话::

在【场景】下，【方法】相对【基线】在【指标】上【效应 ± 置信区间】（n 样本），
该结论在【扫描维度】上成立。

每个方括号是一个必须填的槽。空着的槽就是该问的问题，按"空着的代价" 从大到小排序返回，每个槽带 3~4 个选项。

注意样本数不在槽里——它是由效应量和试点方差算出来的（sw_sample_size）， 把它当问题抛回给用户是把该自己做的功课推回去。

在生成数据之前把主指标与基线定下来（预注册）。

三道门证明不了一件事：主指标是看数据之前定的，还是跑完之后挑出来的 那个最好看的。真实过程往往是——跑完发现平均谱效没提升，顺手换成 5% 边缘用户谱效，有提升就报了这个。每一步都合理，合起来是在多个指标里 挑赢的那个，假阳性率远高于 5%。

做法很轻：写一个 JSON、算个 SHA-256、不可原地改。把返回的 prereg_id 传给 sw_generate，之后 sw_compare_results 会判断用的指标是不是 当初定的：一致 → primary；不一致 → exploratory，结论句里会明说 这不是预注册主结论。

改主意就再调一次，会得到新 prereg_id，旧的不动——"改过口径"这件事 本身留了痕。

给自研算法导出一份评测脚本骨架，让它能进门 2 / 门 3。

内置的 sw_compare_arms 只认六种预编码，自研的 CSI 压缩、信道估计、 波束管理、调度算法进不来。这个工具补那一层：

1. 拿到 code，写进 .py 文件；

2. 把 my_algorithm 的函数体换成你的算法（不改也能跑， 预填的示例是估计 CSI 下的 SVD vs Type I，先确认管道通再换）；

3. 运行它，会注册两个臂并打印 result_id；

4. 把两个 id 交给 sw_compare_results 判决。

MCP 不执行用户代码，脚本在用户自己的进程里跑，只把标准化的逐样本 结果注册回来。逐样本数值落 .npz，不进 MCP JSON。

判决两个外部算法结果，连过门 2、门 3。

与 sw_compare_arms 用的是同一套统计与门控实现，判决标准完全一致 ——自研算法不走宽松通道。区别只在数值从哪来：那个现场跑内置预编码， 这个读已注册的结果。

注册时锁死三件事，任一不成立就拦：数据集内容摘要一致、样本 ID 逐个按序 一致、指标与单位一致。因为配对检验的全部有效性建立在"第 i 个数对应同一个 信道实例"上，错配时它照样会算出一个看起来很显著的 p 值。

返回的 statement 会写清用的哪个检验、指标是什么，以及这是预注册主结论 还是探索性分析。

列出已注册的外部算法结果。不给 dataset_id 就列全部。

算真实吞吐（Mbps）与 3GPP 口径的边缘用户指标，不是香农上界。

sw_link_performance 给的是 SE = Σ log2(1+SINR)——香农谱效，是个 任何真实系统都达不到的上界。这个工具走业界做系统级仿真的标准路径 （链路到系统映射），把三项真实损失算进来：

1. 调制受限 —— 20 dB 时香农说 6.66 bit/s/Hz，64QAM 最多给 5.80

2. 码率离散 —— MCS 只有 29 档

3. 有限码长 + 实现损失 —— LDPC 距容量 1~2 dB

返回吞吐的均值/中位/5% 边缘用户/95% 峰值、谱效、MCS 分布、平均 BLER。 边缘用户吞吐是 3GPP 评估里的公平性指标，比均值更能说明问题。

mcs_table：1 = 最高 64QAM（38.214 Table 5.1.3.1-1）， 2 = 含 256QAM（Table 5.1.3.1-2）。MCS 分布里大量样本压在最高档时， 说明限制来自 MCS 表而不是信道，换表 2 通常能明显提升。

BLER 是模型不是实测：MCS/CQI/TBS 都按 38.214 精确算，QAM 约束容量 精确求积，但 BLER 用的是有限码长模型（没有 3GPP 参考曲线兜底）。 严格 BLER 结论请跑真正的链路级仿真。

查 38.214 的 MCS / CQI 表，以及 BLER 模型各档的门限。

show_bler_anchors=true 时给出各 MCS 达到 10% BLER 所需的有效 SINR， 以及它距同频谱效率的香农极限有多远。这是模型预测，摆出来供人工对照 公开的 NR 链路级曲线——常见量级是 MCS0 约 -5~-7 dB、MCS28 约 20~23 dB。

表格本身是逐字录入的标准值，verify_tables 用"SE == q_m·R/1024"这条 表内蕴关系做过自检。

扫信噪比，出谱效/吞吐 vs SNR 曲线 —— 无线论文里最标准的那张图。

对同一批信道，把工作点信噪比设成一组值，逐点给出香农谱效、实际谱效、 吞吐、选中的 MCS。同一批信道意味着各点之间是配对的，曲线不会被 信道抽样噪声搅乱。

默认扫 -5 ~ 35 dB。返回里 efficiency_vs_shannon 的走势最有信息量： 低信噪比处接近 1（受噪声限），高信噪比处掉下来（受 MCS 表封顶限）。

一个数据集的干扰画像：业务域 IoT + 测量域导频 SIR。只读已落盘的标量。

业务域和测量域是两回事，报告分开给：

• traffic_domain——PDSCH/PUSCH 受到的干扰，用 IoT（噪声抬升 (I+N)/N） 刻画。20 dB 以上算高干扰，同时给出等效小区负载。

• measurement_domain——SRS / CSI-RS 导频受到的干扰，决定信道估计精度。 给出估计 NMSE 的下限。这两列只在 link="BOTH" 生成的数据里有。

IoT 由几何 SIR 与 SINR 精确推出（IoT = SIR/(SIR-SINR)，线性域）， 不是 snr_dB 减 sinr_dB——那两个字段口径不同，相减会差几十 dB。

贴在 ±50 dB 契约边界上的样本、以及没有干扰源的哨兵样本会单独计数而不是 混进统计，notes 里会说明。

IoT 相关的换算与分级。三种用法，给哪组参数就算哪个。

• 给 sinr_db + sir_db：算这一点的 IoT（两者必须同口径， 即都来自几何 SINR 计算，不能拿 snr_dB 凑）。

• 给 iot_db：分级 + 换成等效小区负载。

• 给 load：由等效负载反推 IoT。

等效负载用的是上行极点容量关系 IoT = 1/(1-load)，是解释性换算， 帮助把 "IoT 20 dB" 读成 "等效 99% 负载"，不代表仿真真按这个负载调度。

要构造某个干扰强度的场景，该动哪些旋钮。

不返回保证达标的配置。 IoT 由几何、负载、功率共同决定，唯一可靠的 确认方式是生成一批再用 sw_interference_report 复核。这里给的是方向与 量级，以及各旋钮在 ChannelHub 几何模型里的实际作用——有几个和教科书 直觉不一样，写在每条的 note 里。

花几十秒看清一个场景长什么样，再决定要不要花几十分钟正式跑。

下单之前先看货。 把 num_rb 压到 24、关掉 SSB 测量，几何量与全带宽 逐位相同（实测 273 / 24 / 12 三档，sinr / sir / 路损 / 距离 / 视距 / 多普勒 / UE 位置全部零差异），唯一变的 snr_dB 有解析修正且已修正。 耗时降到约 1/8。

回的是：干扰画像（IoT，多小区才有）、链路预算（SNR/SINR/SIR 分布）、 几何量（路损、距离、视距比例、多普勒）、测量域导频 SIR（link=BOTH 才有）。

not_available 里明确列出探测模式给不了的量——谱效、吞吐、时延扩展 估计、宽带预编码。这些必须跑正式生成，别拿探测结果替代。

参数

preset : 预设名（sw_list_presets 查）。与 config 二选一。 config : 直接给配置。给了 preset 时作为覆盖项。 num_samples : 探测样本数。30 看中位数够用，看 5% 分位建议 100 以上。

并排探测几个场景，回一张对照表。用来在候选场景里选。

每个场景各跑一次探测（见 sw_probe_scenario 的口径说明）， 表里给 IoT 中位数与等级、SINR/SNR 中位数、路损中位数、视距比例、单样本耗时。

典型用法：确认"高干扰"预设确实比"低干扰"对照高出足够的 IoT， 再拿这两个去跑正式对比——别在没验证过干扰水平的两批数据上做消融。