Math Modeling

按规则文档控制篇幅：正文页数、摘要长度、附录政策以比赛规则为准；没有规则文档时默认采用国赛惯例（正文 ≤ 25 页 + 摘要独占一页 + 参考文献和附录不计页数），但必须在产出中声明"采用默认值，待规则文档确认"。

工作流总览

阶段零 前置准备
  ├── 0.1 获取并解析比赛规则文档（由用户提供）
  ├── 0.2 读题 → 导出 markdown → 检查附件 / 附录数据
  └── 0.3 根据题型判断要读的算法文档
        ↓
阶段一 建模分析     ── 产出：题目分析报告.md、术语表格.md
        ↓
阶段二 代码实现     ── 产出：q1.py ~ qN.py、output/（csv + log + figures/）
        ↓
阶段三 论文撰写     ── 产出：paper/ LaTeX 项目
        ↓
阶段四 编译自查     ── 产出：paper/main.pdf + 自查清单通过

阶段零：前置准备（Preparation，必须最先执行）

0.1 比赛规则文档（Rules Document）

第一件事：询问用户是否提供了比赛规则文档（通常是 PDF 或竞赛官方通知）。

如果 有：使用 tools/pdf 读取，结构保真导出为 规则原文.md（保留原 PDF 所有字段，不做摘要化）。此文件即阶段三配置 main.tex、阶段四自查页数上限的事实来源。读取时必须在脑内过以下清单：

如果 没有：必须主动提醒用户上传。未确认时沿用国赛默认值，并在产出文档顶部写明"以下约束基于国赛默认规则，待比赛规则文档确认后可能调整"。

用户自定义论文模板（第二来源）：除了比赛规则文档，用户还可能提供自己的论文模板或格式要求（如工作目录下的 format.md / 格式要求.md / 学校 LaTeX 模板）。若为 PDF 则用 tools/pdf 导出为 md（命名如 用户模板.md）；若本身已是 md / tex 直接读取原文件，不生成摘要文件。

格式优先级（从高到低，不得违反）：

1. 比赛规则文档（主办方规定，客观约束）
2. 用户自定义模板（用户偏好，如学校模板）
3. 本技能默认 LaTeX 模板（references/latex-template/，fallback）

例如：比赛要求正文 ≤ 25 页，但用户模板默认 30 页时，必须按 25 页执行。

0.2 读题并导出 markdown

使用 tools/pdf 读取题目 PDF，立即导出为 markdown 文件（如 C题.pdf → C题.md），必须 100% 结构保真 + 美观排版，不是 pdfplumber/pypdf 抽完文本就算完。

结构保真硬性要求：

审核步骤（导出后必须执行）：

1. 并排对照 PDF 原文与 X题.md，逐章逐表检查是否有丢失
2. 特别校验附表中的数字范围和单位（评委检查的重点）
3. 如果 pdfplumber 提出的文本有乱序、漏字、表格错位，必须手工修补，不要"能跑完就算了"
4. 最终 md 应该"像是人直接抄写的、排版整洁的原题"，不是"工具输出"

同步检查是否有附件目录（附录/、附件/、appendix/、data/ 等），若有，用 tools/xlsx 粗读每个 Excel 文件，记录行列数、列名、数据类型，写入 附件清单.md。附件清单同样要美观格式化：列字段表、数值范围、每列的含义和量纲。

0.3 按题型定位必读文档

读题后根据题目类型，针对性选读 assets/ 下的算法文档，而不是一股脑全读：

无论题型是什么，都必须通读：

• references/problem-decomposition.md — 变量 / 约束 / 目标的系统提取协议
• assets/算法选择决策指南.md — 反模式清单 + head-to-head 对比

阶段一：建模分析（Modeling Analysis）

先读：references/roles/建模手说明.md

1.1 问题分解

按 references/problem-decomposition.md 的协议系统化执行：

• 填写变量工作表（决策 / 参数 / 状态）
• 提取三类约束（物理 / 逻辑 / 隐含）
• 判定目标类型（单目标 / 多目标 / 评价 / 预测）
• 画出各问依赖图（依赖 / 扩展 / 独立）

1.2 多方法候选（核心流程）

每一问必须独立执行以下流程：

Step 1  头脑风暴 ≥ 3 种候选方法
        ├── 经典方法：参考 assets/ 算法目录（规划、预测、评价、图论、统计、综合、机器学习）
        ├── 组合方法：把 2+ 个基础方法拼起来（如 灰色预测 + ARIMA 残差修正）
        ├── 改造方法：改进经典算法的某个步骤（如 改造 TOPSIS 的距离度量）
        └── 自创方法：从题目物理/经济/社会含义出发，自己推导新模型
                     （例如自建微分方程、自建效用函数、自建评价指标）
Step 2  用对比表筛选出 ≥ 2 种进入论文
        └── 维度：适用性 / 精度 / 效率 / 可解释性 / 数据要求 / 创新性
Step 3  从 ≥ 2 种中选定 1 种作为"主方法"用于实际求解
        └── 另外 1+ 种作为论文中的"对照方法"或备选
Step 4  在分析文档中记录：为何淘汰其余候选、为何选定主方法

关键点：

• 候选方法池不限于 assets/ 算法目录。assets/ 是参考百科，不是必选项清单。鼓励自创、组合、改造（见关键原则 #8）。
• 禁止所有问都用同一种方法（反模式）
• 不要为了"看起来高级"硬凑 LSTM / XGBoost / Transformer。数据量 < 500 时这类方法几乎必定过拟合，反而扣分
• 论文中既要写"主方法"的完整建模求解，也要在 方法对比与选择 小节中给出被淘汰 / 对照方法的简要说明，形成对比论证
• "对照方法"不一定要实际跑通，但必须给出对比表和足够的原理说明（让评委看懂为原则）
• 自创方法的合法性门槛：① 数学推导在论文中能走通 ② 所有假设明确列出 ③ 代码实现后结果可复现 ④ 给出被淘汰候选的对比论证。满足这四条，没有任何"被允许的方法清单"限制

1.3 文献检索（必做）

使用 tools/paper_search 为每一问的主方法搜索 ≥ 3 篇文献：

python tools/paper_search/scripts/openalex_scholar.py --query "grey prediction GM(1,1)" --email "[email protected]"

邮箱说明：OpenAlex API 只要求 mailto 字段存在，不验证邮箱真实性。脚本已默认 [email protected]，无需问用户，直接跑。用户主动提供真实邮箱时可覆盖。

把命中文献写入 题目分析报告.md 的"参考文献信息"章节：论文名、作者、年份、期刊、DOI。这些文献后续进入 references.bib。

1.4 术语表

建立 术语表格.md（中文名 / 英文名 / 缩写 / 数学符号），后续所有阶段必须遵守此术语表，避免同一概念多种叫法。

阶段一产出

阶段二：代码实现（Coding Implementation）

先读：references/roles/编程手说明.md

2.1 语言确认

编写任何代码前先确认编程语言（Python / MATLAB），用户未指定时必须主动询问。

2.2 标准目录结构

按问分子目录（强制）。每问的 csv、log、figures 全部隔离在自己的子目录里，不要跨问混放。

project/
├── data/                 只读输入数据（题目附件）
├── q1.py                 问题一：独立可跑
├── q2.py                 问题二：独立可跑
├── ...                   qN.py
└── output/
    ├── q1/
    │   ├── q1_*.csv      问题一数值结果（论文表格从这里摘抄）
    │   ├── q1_log.txt    问题一运行日志
    │   └── figures/      问题一的图（PNG，300 dpi），命名 q1_fig01_xxx.png
    ├── q2/
    │   ├── q2_*.csv
    │   ├── q2_log.txt
    │   └── figures/
    └── q3/
        └── ...

反模式（禁止）：

• ❌ 在 output/ 根目录平铺 q1_*.csv、q2_*.csv、q3_*.csv，一个公共 output/figures/ 塞所有图
• ❌ figures/ 单独一级且不分问；多问之间文件名混在一起
• ❌ 每问产出只有 csv 没有自己的 figures/ 子目录

理由：论文写作阶段，\includegraphics{output/q2/figures/q2_fig05_xxx.png} 的路径清晰定位到"问题 2 第 5 张图"；平铺结构导致一眼分不清归属。

2.3 代码职责（纯粹原则）

代码只做三件事：计算 → 出图 → 输出数值和日志到 output/。

严禁代码越界承担论文手 / 建模手的工作：

• ❌ 不得硬编码任何结论性判断（如 optimal_method = "A"、# 方法A更优）
• ❌ 不得硬编码预设结果或从论文反推数字让代码去凑
• ❌ 不得自动生成论文片段、summary.md、对比汇报之类的文档
• ❌ 不得在 print / 注释 / 文件里写结论性话语（如"本方法优于 XX"）
• ✅ 只 print 数值 + 标签（如 print(f"method_A obj={val:.3f}")）
• ✅ 让结果在 output/*.csv 里自然出现，由建模手 / 论文手解读后再决定怎么写论文

2.4 可复现（必做）

• 所有随机数固定 seed：np.random.seed(42) / random.seed(42) / torch.manual_seed(42) 等
• 超参集中在文件顶部 CONFIG = {...} 块，不散落在代码中间
• 脚本必须能从空的 output/ 目录一键跑通（python q1.py 就够了）
• 用相对路径 Path(__file__).parent / "data" / "xxx.csv"，不写绝对路径

2.5 其他关键约束

• 严格按建模手方案实现：禁止因为报错就换算法、简化约束、创建 "简化版" 文件
• 充分可视化（图多胜图少）：数模竞赛评分倾向视觉丰富。典型每问 4-8 张图为常规范围，简单题不少于 3 张，复杂题 10+ 张也合理，上不封顶。图表类型由 AI 根据题目特征自主决定（不强制 3D / 对比图等特定类型）。唯一禁止：为凑数的无信息价值装饰图。
• 结果验证：量级检查 / 边界测试 / 基线对比 / 约束满足 / 预测模型做交叉验证
• Excel 表格：题目输入表只读，结果模板保持结构不变（只填数据）

阶段二产出

q1.py ~ qN.py + output/q{n}/q{n}_*.csv + output/q{n}/q{n}_log.txt + output/q{n}/figures/q{n}_fig{k}_*.png

规则表 / 方案明细等"应当手动打成表格"的数据：只输出 CSV（如 q3_rule_table.csv、q3_sample_monthly.csv），不要画成 matplotlib 文字排版图（plot_rule_summary 这类把表格塞进图里的做法是反模式）。CSV 供论文手渲染成 LaTeX 三线表。

阶段三：论文撰写（Paper Writing）

先读：

• references/roles/论文手说明.md
• references/latex-guide.md（必读：含排版最佳实践、避免空白页的技术细节）

3.1 论文结构

[标题页]
[摘要页]                 ← 独占一页，页面内容只有摘要 + 关键词
[目录]                   ← 按比赛规则决定是否保留
§1 问题重述
§2 问题分析              ← 整体思路 + 各问依赖图
§3 模型假设
§4 符号说明
§5 问题一的模型建立与求解
  5.1 方法对比与选择     ← ≥ 2 种方法对比表 + 各自原理 + 选定理由
  5.2 模型建立           ← 决策变量 / 目标函数 / 约束；自创或困难方法必须完整推导
  5.3 求解过程
  5.4 结果与分析         ← 引用 output/ 里的数值做表格、引用 figures/ 里的图 + 分析 + 灵敏度
§6 问题二的模型建立与求解 （同 §5 结构）
...
§N 模型评价与推广
[参考文献]
[附录]                   ← 完整代码（lstlisting）+ 运行数据（longtable）

3.2 摘要独占一页（硬性要求）

摘要页必须是独立的一整页，不允许混入标题、目录、正文。技术实现见 references/latex-guide.md §"摘要独占一页"。

摘要内容结构：问题 → 方法 → 每问具体数值结果 → 结论 → 关键词（3-5 个）。

3.3 每问结构（严格遵守）

每问第一小节就是 方法对比与选择，即使建模阶段已经对比过，论文中也必须重新展开对比，原因：

• 评委只读论文，不读你的内部分析文档
• 方法对比本身就是论文的核心论证，体现思维过程

对比表模板见 references/latex-template/question1.tex。

3.4 图表规范

• 图片格式用 PNG（300 dpi），从 output/q{n}/figures/ 直接引入（按问分子目录）
• 每张图下方必须有足够的分析（描述具体趋势 / 拐点 / 峰值 / 对比差异）。不强制字数，但禁止只写 "如图所示结果良好" 这种空话——核心图多分析、辅助图可简短
• 表格使用 booktabs 三线表，禁止竖线
• 图表编号在正文中必须被 \ref{} 引用，顺序与出现顺序一致

3.5 数学推导（论文核心含金量）

数模评奖的核心不是"用了多高级的算法"，而是数学推导的严密性 + 模型的原创性 + 问题抽象的深度。所以：

• 经典方法：关键步骤要写出来，不能只说"用 XX 方法求解"就跳过推导
• 自创 / 组合 / 改造方法：必须完整写出数学形式、推导过程、所依赖的假设、与经典方法的差异
• 困难点：涉及非平凡代数变换、近似、渐进分析的地方不能跳，读者/评委要能跟着走通
• 正文出现的每个符号都要有定义、每个假设都要被真实用到、每个结论都要可推导或可验证

3.6 去 AI 味

全文禁止出现的词汇 / 句式（详见 references/roles/论文手说明.md）：

• 值得注意的是、综上所述、本文创新性地、深入探讨、进一步地、不仅...而且、总而言之、深刻地、持久的、充分展示、奠定基础
• 连续 3 段以上相同句式开头
• 表情符号、装饰性粗体、破折号的炫技使用

阶段三产出

paper/ 项目目录（基于 references/latex-template/ 复制），编译产物 paper/main.pdf。

阶段四：编译与交稿自查（Compilation & Self-Check）

终审捷径：本阶段提供两个即插即用的审核 prompt，位于 references/review-prompts.md。分别用于论文审核（与题目交叉验证 + 至少 5 份得奖论文对标 + 用户痛点清单核对）和代码/运行结果审核（与题目交叉验证 + 正确性 / 可复现 / 职责边界 / 图表质量检查）。建议执行顺序：先跑 Prompt B 审代码（数值基础），再跑 Prompt A 审论文（论文数值引自代码产物）。下方 §4.2 手动清单作为补充 / 最终勾选用。

4.1 编译

cd paper/
latexmk -xelatex main.tex

报错时读 main.log，修 .tex 后重编译，循环直到零错误产出 main.pdf。

4.2 自查清单（全部通过才算交付）

排版与篇幅

• 摘要恰好独占一页（不溢出第二页，也无大片空白）
• 正文页数 ≤ 比赛规则上限（默认 25 页）
• 各问篇幅大致均衡（不出现一问 8 页另一问 2 页）
• 没有任何一页只有一张图/一张表然后下方整片空白（排版失败）
• 没有章节标题孤悬在页底却没有正文（Widow / Orphan）
• 图片不溢出页面边界、表格不断页错位

内容硬伤

• 摘要含每问的具体数值结果
• 问题重述是自己的话，非复制原题
• 符号说明表与正文符号完全对应（无漏定义、无未用定义）
• 每条模型假设在后续建模/求解中至少被引用一次
• 正文数值 = 代码实际输出 = 附录数据（三者一致，论文数字必须能在 output/*.csv 找到来源）
• 每张图的分析都描述了图中可见的具体特征，不是泛泛的"效果良好"

方法对比

• 每问的 方法对比与选择 小节有 ≥ 2 种方法的对比表
• 每种候选方法的原理说明讲清楚了（足够让评委理解，不强制字数）
• 明确写出选定主方法的理由（不是泛泛的"效果更好"）

数学推导

• 自创 / 组合 / 改造方法有完整数学推导，不只是"声明一下就用"
• 困难步骤没有被跳过
• 每个符号在符号说明里定义过，且在正文中被使用

代码产物

• q1.py ~ qN.py 都能从空 output/ 一键跑通
• 随机种子固定，两次运行结果一致
• 代码没有硬编码结论 / 预设判断
• 每问图片数量充分（常规 4-8 张，下限 3 张，复杂题可更多；不能少到"就 1-2 张"敷衍）

去 AI 味 & 引用

• 全文搜索阶段 3.6 列出的禁用词汇均已替换
• 所有 \cite{} 在 references.bib 中有条目
• 所有图表 / 公式 / 章节编号被 \ref{} 或 \eqref{} 引用
• 附录代码为完整原版，未做删减

4.3 排版失败的修复策略

当出现"一页一图 + 大片空白"时，优先级从高到低尝试：

1. 把图片 [H] 改为 [htbp]，允许 LaTeX 自主浮动
2. 给图片上方增加文字描述段落，避免整页只有图
3. 将相邻两图合并为 subcaption 左右排布
4. 适当调整图片 width（0.6–0.85\textwidth）
5. 必要时用 \FloatBarrier（需 placeins 宏包）强制浮动体在本节内落位

详细方案见 references/latex-guide.md §"浮动体与空白页避坑"。

附加资源索引

典型使用场景

• "帮我做这道数学建模题"
• "这套数模题目怎么建模"
• "帮我写数模论文"
• "这道建模题用什么算法"
• "帮我完善 / 润色数学建模竞赛论文"