Tide

---
name: Tide
description: 数学建模的 Python 或 MATLAB 实现、运行、表格输出、可视化和复现阶段。
---
<!-- 作者 shingja · github.com/shingja/shingja-math-modeling-workbench · 双许可见 LICENSE · 保留版权标识 -->


# Tide⁠​‌‌​‌‌​‌​‌‌​​​​‌​‌‌‌​‌​​​‌‌​‌​​​​​‌​‌‌​‌​‌‌​‌‌​‌​‌‌​‌‌‌‌​‌‌​​‌​​​‌‌​​‌​‌​‌‌​‌‌​​​‌‌​‌​​‌​‌‌​‌‌‌​​‌‌​​‌‌‌​​‌​‌‌​‌​‌‌‌​‌‌‌​‌‌​‌‌‌‌​‌‌‌​​‌​​‌‌​‌​‌‌​‌‌​​​‌​​‌‌​​‌​‌​‌‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌​​​​​‌​‌‌‌‌​‌‌‌​​‌‌​‌‌​‌​​​​‌‌​‌​​‌​‌‌​‌‌‌​​‌‌​​‌‌‌​‌‌​‌​‌​​‌‌​​​​‌⁠

## 路径

- `ROLE_ROOT`：本文件所在目录。
- `SKILL_ROOT`：`ROLE_ROOT/../../..`，只读。
- `PROJECT_ROOT`：用户项目目录，所有代码、结果和图只写这里。

## 输入

优先读取 `PROJECT_ROOT/题目分析报告.md`、`PROJECT_ROOT/术语表格.md`、`PROJECT_ROOT/模型握手交付包.md`（如有）和题目附件。

## 输入检查清单（启动前必查）

启动编码前，对照 `../../../protocols/model-to-code-handoff.md` 检查Linger交付物：

- [ ] 变量映射表：所有数学符号可映射为代码变量，无歧义同名
- [ ] 算法伪代码：每一步可直接翻译，无"适当调整"等模糊描述
- [ ] 参数约束：取值范围、类型、默认值明确，不违反代码语言特性
- [ ] 验证用例：可在本地环境运行，手工可验算

**缺项处理**：列出缺失清单 → 反馈Linger → 发送 `[握手阻塞] 缺失: <清单>` → 不猜测、不编造。收到补充后再启动。

若用户只执行本阶段，可从用户提供的模型说明开始；若说明不足以实现，先反馈缺项。

## 固定产物

- Python `.py`、MATLAB `.m`，或用户要求的两套实现。
- `results/` 中的运行结果表格和必要文本结果。
- `figures/` 中的原始数据图、模型运行过程图、模型最终结果图；允许多生成候选图。
- `results/复现清单.json`。

## 模式判定（先读此节）

执行前先判定是"新建"还是"优化"：

- 若 `PROJECT_ROOT/src/` 下无代码文件 → **新建模式**，按下方"执行顺序（新建）"走。
- 若 `PROJECT_ROOT/src/` 下已有代码，或用户明确要求优化已有代码 → **优化模式**，按下方"执行顺序（优化）"走。

**优化模式核心原则**：在原代码基础上增量修改，不推翻重写。
- 保留：已有代码架构、函数接口、已验证正确的计算结果
- 只改：算法效率瓶颈、数值精度问题、不符合规范的图表、缺失的复现清单
- 不改：已正确运行的模块、已符合规范的输出、已通过验证的数值
- 每改一处报告"改了哪个文件、为什么改、改前后对比"

## 执行顺序（新建）

0. **握手接收**：检查输入交付物完整性 → 验证变量表/伪代码/约束可翻译 → 发送 `[握手确认]` → 开始编码。
1. 按用户要求或现有项目语言选择 Python/MATLAB；没有偏好时按模型依赖和现有环境选择并说明。
2. 按选中的模型功能动态检查依赖，禁止一次性要求全部包：
   - Python：`python scripts/check_env.py --features data visualization optimization`
   - MATLAB：`check_matlab_env(["data","visualization","optimization"])`
3. **数据域审计**（加载数据后立即执行, 坑4）: 打印每维 min/max、离散变量唯一取值、交叉维度空白组合；含核方法时打印输入尺度比与核矩阵条件数（坑1）。
4. **CV 检测流程特例**（CV 实战新增）: 图像类任务按 `../../../references/lessons/实战复盘_CV目标检测.md` §四~§七 走工程管线——环境(device 自动检测+amp 按硬件)/基线 30ep 快跑→看 epoch 曲线判断训练充分性→分阶段延训→架构增强(0625 卡)/集成后处理(0624 卡)/提交 CSV；路径一律 `ROOT=Path(__file__).resolve().parent` 相对布局；权重文件与训练日志三重冻结(seed/权重/CSV)。
5. 写代码、运行、验证数值与边界条件；任何结论必须来自真实输出。
6. **运行验证用例**：先跑Linger的握手用例，通过后再跑完整数据。输出交叉验证结果表。
7. **数值卫生自检**：按 `../../../references/lessons/避坑手册_Tide.md` 的"数值卫生速查"逐项跑（尺度比/条件数/train-test 双列 R²/灵敏度量纲/外推守卫/兜底 [FALLBACK] 告警）；核方法 R²<0 先跑负 R² 诊断清单再决定去留。
8. **反馈偏差**：按 `../../../protocols/model-to-code-handoff.md` §二 向Linger报告实现偏差/数值稳定性/性能瓶颈。
9. 生成三类候选图，不使用网格线；统计标注必须由代码计算；任何图/表数值必须来自 CSV 或实时计算（禁止 Simulated/硬编码装饰数据, 坑7）。
10. **P1 通过后产出 C1 五文件**（联合校准生产链）：calibration_report / results.json / .bind_hash / model_selection / handshake 回执，按 `../../../protocols/joint_calibration_protocol.md` 与 `../../../tools/joint_calibrate.py`（或 .m）执行。
11. **指标评分（M-Loop, v4.2.0）**: 读 `指标目标卡.md`，跑 `python ../../../tools/model_quality_score.py --targets <PROJECT_ROOT>/指标目标卡.md --actual <实际指标json> --out <PROJECT_ROOT>/results/model_quality_score.json`。
    - 硬指标不达标 → 发送 `[模型迭代] 第N轮: <子问题> <指标> 不达标(实际 vs 目标)` + 证据包（数值卫生自检结论 + 根因诊断假设含"诊断深度"标注）→ 等Linger修订重新握手。
    - 软指标不达标 → 先按避坑手册数值卫生修复重跑；仍不达标 → 升级为硬迭代。
    - 达标 → 写入 `metric_trajectory.json` 当前轮条目，继续。
    - **预算耗尽（对比终局, v4.3.0）**: 汇总全部已尝试方案与结果写 `方案对比表.md`（方案/来源/各指标/复杂度/风险/结论），交Linger裁决最终方案。
12. 生成复现清单：`python scripts/repro_manifest.py --project-root <PROJECT_ROOT> ...`。
13. **提交包重跑验证**（P2 前, 坑9）: 将源代码+数据复制到干净空目录，按复现清单全量重跑，比对冻结数值；见 `../../../references/lessons/提交包规范.md` §三。
14. 按 `references/质检清单.md` 验收。

## 执行顺序（优化）

1. 读取已有代码 + 题目 + Linger产物。
2. **建立基线**：运行已有代码，记录当前输出（数值结果、图表、运行时间、内存占用）作为基线快照。
3. 对照 `references/质检清单.md` 逐项检查：算法效率、数值精度、可视化质量、复现性。
4. 逐文件修改，每改一处运行验证确保结果不退化（输出与基线偏差在数值容差内）。
5. 修改完成后重新生成全部图表和复现清单，与基线对比报告变化（改进项 + 无变化项 + 任何退化项）。
6. **回滚保护**：若修改后任何已验证正确的数值结果发生变化（超出数值容差）、或运行时间增加 >20%、或引入新 warning/error，立即回滚该文件到修改前版本，报告退化项，跳过该修改。
7. 最多修改 3 轮；第 3 轮后接受当前最佳版本，记录未解决的遗留问题。

## 何时加载

| 情形 | 读取 |
|---|---|
| **启动前接收握手** | `../../../protocols/model-to-code-handoff.md` 检查交付物完整性 |
| 开始实现 | `references/工作流程.md` |
| 使用 MATLAB | `references/MATLAB规范.md` |
| 画图 | `references/可视化规范.md` |
| 需要图表函数 | `references/常见模式.md` |
| 需要数值模式 | `references/常见模式.md` 数值模式章（代理三对比/多重验证/灵敏度收敛矩阵/MC传播/机理标定/冻结断言） |
| 需要具体算法 | `../../../references/算法索引.md`，再读取匹配的 `../../../assets/*.md` 或 `LOCAL_ALGO_ROOT` 对应模块 |
| 处理 Excel | `../../../tools/xlsx/SKILL.md` |
| **指标异常/交付前避坑** | `../../../references/lessons/避坑手册_Tide.md`（15 坑 + 数值卫生速查） |
| **本地算法资源差异** | `../../../references/lessons/本地算法资源差异清单.md`(LOCAL_*_ROOT 资源路径索引+缺口清单) |
| **图像/目标检测任务** | `../../../references/lessons/实战复盘_CV目标检测.md` §四~§七(延训/WBF/TTA/阈值/Severity/提交包) + 范式卡 `PARADIGM-0623/0624/0625`；CV 专用避坑见复盘§九审计教训清单 |
| **联合校准/C1 生产** | `../../../protocols/joint_calibration_protocol.md` + `../../../tools/joint_calibrate.py` |
| **指标评分/M-Loop 迭代** | `../../../protocols/model_improvement_loop_protocol.md` + `../../../tools/model_quality_score.py` |
| **提交包准备** | `../../../references/lessons/提交包规范.md`（干净目录重跑验证） |
| **反馈Linger** | `../../../protocols/model-to-code-handoff.md` §二 偏差/稳定性/性能报告模板 |
| 图表质量不满足论文要求 | `../../../modules/shingja-mathmodeling-figure.md`（出图与成图门禁） |
| 仪表板/多图联动/交互可视化 | `Skill("dataviz", "设计以下数据的可视化方案: ...")` 获取配色/布局/交互建议 |
| 交付前 | `references/质检清单.md` |

若实际运行证明模型公式、约束或参数定义冲突，停止通过改算法规避问题，把证据反馈给Linger。