166 lines
7.3 KiB
Markdown
166 lines
7.3 KiB
Markdown
# mcm26b — CUMCM 2026 B 题：无线电干扰源的快速自动定位与清除
|
||
|
||
本仓库为参赛论文（`docs/paper/main.tex`）的可复现支撑材料：
|
||
提供四问的完整可运行程序、自建模拟器、论文全部数据与插图的生成脚本。
|
||
算法本身的推导、证明与结果分析见论文，本文件只说明**怎么跑、怎么复现**。
|
||
|
||
---
|
||
|
||
## 1. 环境
|
||
|
||
- Python ≥ 3.10；运行时依赖仅 `requests`，测试与自检另需 `pytest`、`numpy`。
|
||
- 自建模拟器 `referee/` 为零第三方依赖的独立包，`uv sync` 时作为开发依赖一并挂载。
|
||
- 复现论文 PDF 另需 TeX Live（XeLaTeX、ctex、TikZ），字体已随仓库提供于 `docs/paper/fonts/`。
|
||
|
||
```bash
|
||
uv sync # 安装主包与 referee（可编辑挂载）
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 运行程序（问题三 / 问题四闭环）
|
||
|
||
**队号不在代码中固化**：登录标识属身份信息，一律在运行时通过 `--robot-id` 传入，
|
||
代码、测试、示例与日志中只出现与赛事无关的中性占位符（如 `TEAM-0001`）。
|
||
|
||
```bash
|
||
# 对接官方模拟器（先在界面确认测试已开始、接口就绪）
|
||
uv run python -m mcm26b.cli run --robot-id <队号> --problem 3
|
||
uv run python -m mcm26b.cli run --robot-id <队号> --problem 4
|
||
|
||
# 一键本地评测：自动起自建模拟器 → 开一局演练 → 跑完整闭环 → 汇总
|
||
uv run python -m mcm26b.cli run --robot-id <队号> --problem 3 --local-judge
|
||
|
||
# 不连任何模拟器的自检（随机场景，内存回环）
|
||
uv run python -m mcm26b.cli run --robot-id SELFCHECK --problem 3 --self-test
|
||
|
||
# 复现附件计时示例（期望 105/111/194/199 秒）
|
||
uv run python -m mcm26b.cli sim-check
|
||
```
|
||
|
||
主要开关：`--strategy {bayes,seven,grid}`（仅问题三，默认 `bayes`）、
|
||
`--base-url`、`--log <路径>`、`--real-budget-s`（仅自检生效）。
|
||
|
||
### 问题一 / 问题二
|
||
|
||
```bash
|
||
uv run python -m mcm26b.cli q1 examples/q1/normal.json -o output/q1/result.json
|
||
uv run python -m mcm26b.geometry examples/q1/triangle.json
|
||
```
|
||
|
||
`examples/q1/` 下的五个算例分别覆盖正常多边形、劣交会、零误差线段、不相容观测与直径圆反例。
|
||
|
||
仓库根的 `main.py` 只是转发到同一 CLI 的薄壳（`python main.py <子命令>`），
|
||
等价于 `python -m mcm26b.cli <子命令>`。
|
||
|
||
---
|
||
|
||
## 3. 自建模拟器（`referee/`）
|
||
|
||
按题面附件 1《模拟器使用说明》与附件 2《通信接口说明》实现，与参赛队代码零耦合，
|
||
只通过 HTTP 协议对接；论文正文的演练数据即由它产生。
|
||
|
||
```bash
|
||
uv run python -m referee # WebUI http://127.0.0.1:8026，接口 :2026
|
||
uv run python -m referee --data-dir referee-data
|
||
```
|
||
|
||
- WebUI 复现官方测试流程：四个模块（演练不限次 / 正式各 3 次）、确认→5 秒倒计时→
|
||
25 分钟窗口、指令与反馈流、中止需两次确认、结束原因、行为日志导出；
|
||
- "回放"页可用本局行为日志动画复现运动与扫描过程，也支持手动导入任意 JSONL；
|
||
- 自建差异（联网登录、官方校时、加密上传属官方服务器侧，本地不实现；
|
||
误差场与场景分布为测试假设）见 `referee/README.md`。
|
||
|
||
---
|
||
|
||
## 4. 复现论文数据（`referee-data/` → 宏与表格）
|
||
|
||
`referee-data/sessions/` 收录论文正文引用的 44 局演练日志（问题三 15 局、问题四 29 局），
|
||
`referee-data/rejected-sessions/` 保留同批采集中被判定为无效的 11 局以便复核。
|
||
|
||
```bash
|
||
python scripts/build_practice_data.py # 复算演练局 → 宏、整表、CSV/JSON 快照
|
||
python scripts/audit_paper_formal.py --snapshot docs/paper/data/formal-results.json
|
||
python scripts/build_paper_support.py # 附录正式数据表与支撑包
|
||
```
|
||
|
||
- 第一条按题面计时模型逐动作复算，输出 `docs/paper/data/practice-*.tex` 与
|
||
`practice-results.{json,csv}`；复算值与评测机记录的最大偏差应为 **0.000000 s**。
|
||
运行结束会打印局数、全清局数与平均虚拟时间，可直接与论文数字对照。
|
||
- 第二条校验官方六份正式导出包与统计快照的对应关系（来源匹配需原电脑的官方统计队列）。
|
||
- 第三条生成附录表格与 `support-materials.zip`（`--package`）。
|
||
|
||
### 需要重新采集演练局时
|
||
|
||
```bash
|
||
uv run python scripts/run_practice_episodes.py --problem 3 --robot-id <队号> \
|
||
--counts 10,13,16 --seeds 300-314
|
||
uv run python scripts/run_practice_episodes.py --problem 4 --robot-id <队号> \
|
||
--counts 10,13,16 --directional-cycle 3,6,8 --seeds 400-439
|
||
```
|
||
|
||
脚本启动评测机并调用生产策略对接接口，真值与行为日志由评测机写入
|
||
`referee-data/sessions/`。判定标准为
|
||
`清完全部源 ∧ 无缺席误判 ∧ 主动退出 ∧ 零异常 ∧ 零失败清除`；
|
||
只看"是否清完"会放过"清完了但中途大量 `/clear` 打空"的无效局。
|
||
|
||
---
|
||
|
||
## 5. 复现论文插图
|
||
|
||
```bash
|
||
uv run python scripts/plot_paper_figures.py # 生成 docs/figures/*.png
|
||
```
|
||
|
||
脚本只读 `docs/paper/data/` 下的复算结果与第四问覆盖计划，不手抄任何数字；
|
||
图内文字与图注数据均来自同一次复算。插图清单、数据来源与生成命令见
|
||
[`docs/figures/README.md`](docs/figures/README.md) 与 `docs/figures/manifest.json`。
|
||
|
||
---
|
||
|
||
## 6. 编译论文
|
||
|
||
```bash
|
||
cd docs/paper
|
||
latexmk -xelatex -interaction=nonstopmode -halt-on-error -outdir=build main.tex # 产物 build/main.pdf
|
||
latexmk -xelatex -interaction=nonstopmode -halt-on-error main.tex # 产物 main.pdf
|
||
```
|
||
|
||
两条口令都完成交叉引用所需的多遍编译。VS Code 的 LaTeX Workshop 配置见
|
||
`.vscode/settings.json`（默认配方为前者）。细节与注意事项见
|
||
[`docs/paper/README.md`](docs/paper/README.md)。
|
||
|
||
---
|
||
|
||
## 7. 单文件核心代码与测试
|
||
|
||
```bash
|
||
uv run pytest # 全部测试（本包 + referee）
|
||
python scripts/build_core_notebook.py # 由 src/mcm26b 生成单文件核心代码
|
||
python scripts/run_notebook_cells.py # 顺序执行 notebook 全部代码单元（零依赖自检）
|
||
```
|
||
|
||
[`mcm26b-核心代码.ipynb`](mcm26b-核心代码.ipynb) 是四问生产实现的单文件版本
|
||
（约 5000 行），不含评测机、命令行外壳、采集/绘图脚本与测试；
|
||
`src/mcm26b/` 保留与之逐字对应的模块化版本。
|
||
|
||
---
|
||
|
||
## 8. 目录结构
|
||
|
||
```
|
||
src/mcm26b/ 四问求解实现：config / protocol / geometry / belief / coverage /
|
||
guarantee / planner / particles / routing / evaluation / harness
|
||
referee/ 自建模拟器（独立包，零第三方依赖，不依赖本队代码）
|
||
referee-data/ 论文数据来源：演练日志（sessions / rejected-sessions）、正式统计快照
|
||
tests/ 本包测试（含运行时零导入 referee 的解耦守卫）
|
||
docs/paper/ 论文 LaTeX 源、数据与宏、编译说明
|
||
docs/figures/ 论文插图（PNG）与来源清单
|
||
examples/ 问题一算例与回放归档
|
||
scripts/ 复现脚本：数据复算、插图绘制、正式数据核对、采集与基准
|
||
project/ 四问"最优实现 / 基线实现"配对对比框架（论文对比表的来源）
|
||
issue/ 赛题、附件与格式规范（原始材料）
|
||
```
|
||
|
||
`docs/paper/REWRITE_NOTES.md` 记录论文各轮修订与验证过程（含数据重采与问题修复）。
|