---
name: comp-simulation
description: "仿真建模主链：方法选型（多智能体/离散事件/系统动力学/连续系统/蒙特卡洛/数据驱动融合）、模型规格化、校准与校核验证、实验设计与重复运行纪律、敏感性分析与不确定性量化、仿真产物契约。用于仿真建模类竞赛（如全国大学生仿真建模应用挑战赛）与仿真研究报告。"
argument-hint: [problem-statement-or-scenario]
allowed-tools: Bash(*), Read, Write, Edit, Grep, Glob, WebSearch, WebFetch, Agent
---

# 竞赛仿真建模主链

从赛题/场景到可复现仿真结论的单一入口：**$ARGUMENTS**

> **定位**：这是**方法论 + 契约 + 编排**技能，不是仿真引擎。它决定"该用哪类仿真、模型怎么规格化、
> 结果怎么才算可信、产物怎么落"，并把执行路由到具体引擎（Mesa / SimPy / Salabim / PySD / pymoo /
> stable-baselines3 / PyMC 等，见 `references/engine-routing.md`）。
>
> **与相邻技能的边界**：数学建模主链（`comp-modeling` / `comp-code`）负责"建方程、写代码"；
> 本技能负责**仿真特有的四件事**——①方法选型 ②随机性纪律 ③校准与校核验证 ④置信区间与不确定性。
> 定了型之后，求解与写作仍走既有 `comp-modeling` → `comp-code` → `paper-figure` → `comp-paper-zh` 主链。

---

## 0. 开场先跑（方法未定不写代码）

```bash
# 引擎可用性探测（不联网、不安装，只报告）
python skills/comp-simulation/scripts/sim_env_probe.py
```

探测结果决定可选路径：缺席的引擎**如实记为 unavailable，不阻断**——本技能的方法论层（选型/V&V/实验设计）
不依赖任何特定库，纯标准库即可执行最小仿真。

---

## 一、方法选型决策树（先定性，再动代码）

按**系统的主导特征**选，不按"哪个库我会用"选。

| 主导特征 | 方法 | 首选引擎 | 关键产出 |
|---|---|---|---|
| 大量异质个体、个体间交互/博弈、涌现 | **多智能体（ABM）** | Mesa（`mesa` / `mesa-geo`） | 个体规则表 + 演化曲线 + 情景对比 |
| 流程/排队/资源竞争，事件驱动的离散状态跳变 | **离散事件仿真（DES）** | SimPy（描述性）/ Salabim（带动画） | 流程图 + 资源利用率 + 等待时间分布 |
| 反馈回路、存量-流量、政策杠杆（宏观总量） | **系统动力学（SD）** | PySD（读 Vensim/标准 SD 方程） | 因果回路图 + 存量流量图 + 政策情景 |
| 连续状态由微分方程演化（物理/生态/流体） | **连续系统仿真** | SciPy `solve_ivp` / `scipy.integrate` | 状态轨迹 + 相图 + 守恒量校验 |
| 输入不确定、要传播到输出分布 | **蒙特卡洛** | NumPy（自写）/ SALib（敏感性） | 输出分布 + 置信区间 + 方差分解 |
| 有真实数据、要让数据校准或替代机理 | **数据驱动融合** | scikit-learn / PyMC / stable-baselines3 | 校准参数后验 + 代理模型精度 |
| 多目标、要 Pareto 前沿 | **仿真优化** | pymoo（NSGA-II/III、MOEA/D） | Pareto 前沿 + 权衡表 |

**混合是常态**：ABM + 蒙特卡洛（个体规则含随机）+ pymoo（多目标调度）是最常见的 A/C 赛道组合。
混合时**必须分别声明各层的角色**（谁是机理、谁是优化器、谁是抽样器），否则结论归因不清。

### 赛道映射（全国大学生仿真建模应用挑战赛 A/B/C）

- **A 多智能体复杂系统仿真**：ABM 为主（Mesa），配 SD 或 DES 做宏观/流程层；重点是**智能体规则设计 + 群体调度优化 + 演化风险研判**。
- **B 全域数字孪生建模与治理仿真**：DES/SD 为机理层 + **空间与可视化层**（GIS/三维）；重点是**虚实映射与态势推演**。
  ⚠️ **本仓无三维孪生渲染资产**（见 `references/engine-routing.md` §缺口）：选 B 前必须先确认可视化链路可行，否则如实降级为"二维态势 + 数据孪生"并声明。
- **C 数据驱动仿真融合与智能优化决策**：数据校准（PyMC/回归）+ 仿真底座（任一类）+ 智能优化（pymoo/RL）；重点是**数据-算法-仿真双向赋能**的闭环叙事。
  ⚠️ **防退化**：只有 ML 没有仿真底座 = 退化成普通数据建模，与赛道定位不符。必须保留显式仿真时钟与推演过程。

详版决策树与反模式见 `references/method-selection.md`。

---

## 二、模型规格化（写代码前先落这张表）

**仿真模型的五要素**必须显式写出，缺一项即为不可复现模型：

1. **实体（Agent/Entity）**：类型、状态变量、属性、数量——个体差异从哪来？
2. **规则（Rule）**：状态转移/决策规则、交互规则、学习规则。**每条规则要有出处**（赛题给定 / 文献 / 假设）。
3. **环境（Environment）**：空间（网格/网络/连续）、边界条件、外部驱动（天气/需求/政策）。
4. **时钟（Clock）**：仿真时间语义（离散事件 / 固定步长 Δt / 混合），**时间推进单位与总时长**。
5. **观测量（Observation）**：跑什么指标、在什么时间点记录、聚合口径。

**随机性纪律（仿真与普通建模的分水岭）**：

- 每个随机源**独立显式**（`default_rng(seed)` 一律显式建 Generator，禁用全局 `np.random`）；
- **种子表**：每个情景的种子写进 `SIM_MANIFEST.json`，可重放；
- **重复次数 N** 由输出方差的置信区间反推（见 §四），**不得用 N=1 报结论**；
- 随机数消耗顺序变化会改变结果——**改代码后必须重跑并对比是否仅由顺序变化引起**。

---

## 三、校准、验证与确认（V&V——评分最容易丢分处）

三类工作，缺一类则结论不成立：

| 类别 | 问什么 | 怎么做（可机检的做法） |
|---|---|---|
| **验证 Verification** | 模型**实现**对不对？（代码 ≠ 规格） | 极端参数极限行为；已知解析解对比；守恒量/流量平衡校验；单元测试化小场景 |
| **校准 Calibration** | 参数取什么值？ | 历史数据/官方数据集拟合；网格或贝叶斯（PyMC）出后验；**报参数不确定区间** |
| **确认 Validation** | 模型**对不对**于真实系统？ | 留出期/留出场景外推对比；与基准方法对照；专家可解释性检查 |
| **不确定性量化 UQ** | 结论有多稳？ | 蒙特卡洛传播输入不确定 → 输出分布；方差分解（SALib Sobol） |

**基线对照是硬要求**：任何仿真结论必须有一个"更笨的对照"（历史均值 / 简单排队公式 / 无干预情景）——
没有对照的提升百分比不成立。清单见 `references/vv-checklist.md`。

---

## 四、实验设计与运行纪律

- **因子表**：列出可控因子、水平、固定因子（写死并声明）、噪声因子。
- **DOE 优先**：因子多时用因子/部分因子设计或拉丁超立方（`experimental-design` 技能 / pyDOE3），
  不要用"逐个改一个参数"的全组合浪费算力。
- **重复与置信区间**：同一情景跑 N 次（种子 1..N），报 **均值 ± t 置信区间**；
  N 的确定：先跑 30 次估 σ，再按目标半宽反推 N。
- **热身期（warm-up）**：稳态指标必须丢弃瞬态段，**说明截断准则**（如均值漂移 < x%）。
- **预算与可复现**：单次运行时长 × 情景数 × N 必须落在赛时预算内；
  超预算先降 N 或降情景数并**声明精度损失**，不得静默缩减。

---

## 五、敏感性、不确定性与稳健性

1. **局部敏感性**：单参数 ±x% 对输出的弹性（OAT，仅作初筛）。
2. **全局敏感性**：Sobol/Morris（SALib），出**一阶/总阶指数排序**——说明"哪个参数真正决定结论"。
3. **稳健性**：在参数不确定区间内重复，检验结论**是否翻转**。翻转即结论脆弱，必须如实降调措辞。
4. **极端情景**：最好/最坏/临界点，检验模型不产生非物理输出。

---

## 六、产物契约

**必须落 `SIM_MANIFEST.json`**（校验器：`scripts/sim_manifest_check.py`）：

```json
{
  "method": "abm|des|sd|continuous|montecarlo|data-driven|hybrid",
  "hybrid_roles": {"mechanism": "...", "optimizer": "...", "sampler": "..."},
  "engine": {"name": "mesa", "version": "3.x", "available": true},
  "time": {"semantics": "discrete_event|fixed_step", "dt": null, "horizon": 100, "unit": "day"},
  "entities": [{"type": "vehicle", "count": 40, "state_vars": ["soc", "pos"]}],
  "randomness": {"generator": "np.random.default_rng", "seeds": [1,2,3], "replications": 30},
  "observations": [{"metric": "makespan", "aggregate": "mean", "ci": "t95"}],
  "calibration": {"params": {"v": 12.5}, "source": "...", "uncertainty": "±0.8"},
  "vv": {"verification": ["..."], "validation": ["..."], "baseline": "..."},
  "runs": {"total": 30, "wall_clock_s": 42.5, "artifact": "results/sim_runs.csv"}
}
```

**结果账本**：每个情景一行（情景 id、参数、N、均值、CI、备注），落 CSV/JSON；
论文中出现的每个仿真数字都必须能追到这张账本（与 `comp-consistency` 的 facts 口径一致）。

**图**：仿真特有必出图——①演化曲线（含置信带）②情景对比 ③敏感性排序（Sobol 条形）④相图/热图（空间类）。
制图走 `paper-figure` / `figure-craft`，配色走统一注册表。

---

## 七、论文与视频槽位

- **论文**：仿真专章建议结构 = 问题与机理 → 模型规格（五要素）→ 校准与 V&V → 实验设计 → 结果与情景对比 → 敏感性/稳健性 → 管理启示。
  写作走 `comp-paper-zh`（中文）；引用与去 AI 味按主链既有契约。
- **仿真视频**（本赛事为**必要**交付件）：展示 ①界面与功能模块 ②运行过程（录屏，关键参数特写）③结果与可视化。
  规格与制作链路见 `references/deliverables.md`；录制走执行环境自带录屏（或系统录屏工具）或 CDP screencast，剪辑/压缩走 ffmpeg。
- **反 AI 味**：仿真视频的旁白/字幕与论文文字同受赛事 AIGC 审查口径约束（本赛事当届阈值未取证，
  首届为 AIGC>30% 即判雷同——按保守对待）。

---

## 八、完成铁律

1. **无 `SIM_MANIFEST.json` 即未完成**——校验器 exit 非 0 不得宣称完成。
2. **无基线对照即结论不成立**——每个核心结论必须写出对照是什么。
3. **N=1 的运行不构成证据**——单次结果只能作为调试输出。
4. **种子必须落盘**——不可复现的仿真结论按未执行处理。
5. **缺席引擎如实登记 `unavailable`**，不得虚构运行证据；方法论层不依赖特定库。
6. **数值口径跨文件一致**——账本、论文、图、视频字幕的数字必须逐项对齐。

## 预期行为

- 收到赛题后**先出选型论证 + 五要素表 + V&V 计划**，经确认再写代码；
- 每轮运行落盘 manifest 与账本，**增量追加不覆盖**；
- 结论句一律带置信区间或稳健性限定词。

## 异常处理预案

| 现象 | 处置 |
|---|---|
| 引擎未安装 | 记 `unavailable`；降级纯标准库最小实现（方法与契约不变），并在交付中声明 |
| 运行超时 | 先降 N 再降情景数，逐级声明精度损失；不得删情景不留痕 |
| 结果对种子极敏感 | 提高 N 并报分布而非点值；若仍不收敛 → 模型本身不稳定，须回到 §二 改规格 |
| 校准无数据 | 用文献值/合理区间 + 全局敏感性替代，**明确标注为"未校准"** |
| 与基线相比无提升 | 如实报告；把"为何无提升"写成分析，而不是调参凑数 |