- name
- computational-realization
- description
- Meta-model-agent 将数学机制落地为可运行程序、数值实验、结果合同与可复核证据。适用于计算实验实现。
# 计算实验工程实现
## DATA_PREPARATION 条件子流程
它属于 COMPUTATION,不是第八阶段。有数据时先执行 `程序/data_preprocessing.py`:校验原始数据,按 FORMULATION 合同实施题目专属处理,比较处理前后质量,把唯一规范输入冻结到 `数据/processed/`,然后模型程序只读取该输入。将源文件路径/哈希、步骤、质量统计、泄漏控制和处理后文件路径/哈希写入现有 `图表/全部结果.json.data_preparation`,并在 `计算结果.md` 留一段摘要。无数据时不得创建这些伪产物。
对 `new_model/model_extension` 子问题,在现有 `图表/全部结果.json.model_identity` 中按 `Q1/Q2/...` 写入 `academic_name`、`canonical_model_family`、`solver_algorithm`、`objective_count`、`objective_direction`、`variable_type`、`relation_type` 和 `multiobjective_evidence`。各项值必须直接复制 `建模报告.md` 审计身份与模型语义卡。`comparison/validation/application` 子问题不伪造模型身份,只在计算结果中记录其继承模型和真实比较或验证证据。
## 发布声明与新增机制验证
在同一个 `图表/全部结果.json` 中维护 `publication_claims`,逐问至少登记一项进入论文的关键结果,包含 `question`、`statement`、`display_value`、`source_key`、`derivation` 和 `required_in`。直接结果使用 `derivation: direct`;加总、区间并集、均值、比率或归一化结果必须写明真实派生方式。论文只读取该账本,不另造数字。
对 `model_extension` 验证新增机制:新增时序检查先后和边界精度,新增资源检查边际贡献、重叠与闲置,新增分配检查容量和分配后可行性,新增随机机制检查情景外可行率。元启发式或混合求解至少报告可行基线、全局阶段结果、局部精化增益、重复运行分布和最终约束残差中适用的项目。
灵敏度分析必须记录指标定义、扰动范围、固定决策或重新优化、可行率和响应方向。不得把低灵敏度或零灵敏度直接写成“模型正确/鲁棒”。
## 稳定执行契约
- **执行目标**:把建模报告中的每个子问题实现为可运行程序,并冻结真实计算结果与复核证据。
- **调用参数**:[modeling-report-or-topic]。
- **权威输入**:建模报告.md、问题分析.md、用户数据及已确认的参数。
- **允许交付**:程序/、程序/code_manifest.json、计算结果.md、图表/全部结果.json、依赖清单.txt,以及必要的日志和状态记录。
- **禁止写入**:不得越权修改已冻结的上游事实、用户原始文件或本协议未授权的目录。
- **可用工具边界**:Bash(*), Read, Write, Edit, Grep, Glob, Agent。
- **最小交付**:逐问可执行程序、主程序.py、代码清单与源码哈希、结果 JSON、发布声明、运行记录、基线比较、差异化验证、约束残差与失败说明。
- **恢复入口**:优先读取当前工作、状态记录和已有产物,从最近一次通过门禁的位置继续。
- **失败回退**:执行失败时定位到数据、实现或模型层;只允许有证据的修复,模型根本失效时回退数学机制构造。
- **收口顺序**:先核对输入,再完成产物,再运行本环节门禁,最后登记状态;门禁未通过不得宣告完成。
依据建模报告编写代码并实施计算:**$ARGUMENTS**
## ⛔⛔⛔ 工作项规模警示(先读这段, 再读后面全部内容)
**这不是简单工作项。** 数学建模竞赛的 computational-realization 环节要把建模报告里**各个**子问题落地成可跑的代码 + 真实结果。
子问题数量由 建模报告.md 决定(一问也可能, 多问也可能), 不是固定的。
⛔ **判定你是否真的做完了**, 在 `end_turn` 此前自问:
1. 建模报告.md 里有几问?你是不是真的为每问都写了独立的 .py?
2. `图表/` 下是不是每问都有相应的 `问题_*_结果.json` 且文件非空?
3. 计算结果.md 是不是已经出现, 涵盖每问的方法和数值结果?
4. 跑过完成铁律最后那段 bash 校验脚本了吗?
**任何一项答 "否" → 避免 `end_turn`, 继续干活。** 引擎会反复检测这些产物, 没产出会自动化重新拉你回来重做, 与其被动重做不如一次做完。
⛔ **避免用 "我已经做了重点工作, 剩下的晚点再说" 的心态退出**。
"晚点" 在 LLM 单轮预算里不出现 — 当 `end_turn`, 你就被切断了, 下一次进来要重新读上下文 + 重新理解工作项, 比当前继续干活贵得多。
## 输入
1. **建模报告.md** — 建模报告(务必出现)
2. **问题分析.md** — 问题情境解构报告
3. **选题规划.md** — 选题规划(统计建模,含图形与表格预规划)
4. **用户数据/** — 赛题附件数据
## ⛔⛔⛔ 完成铁律(最高优先级,违反则当前环节失败)
**当前环节务必产出 `计算结果.md`(≥ 1KB)+ `程序/主程序.py`(≥ 500 字节)+ 不少于 1 个 `图表/*.json`**。
⛔ **结束前必跑产出校验**:
```bash
PASS=true
[ -f 计算结果.md ] && SZ=$(wc -c < 计算结果.md) || SZ=0
[ "$SZ" -ge 1024 ] && echo "✅ 计算结果.md ($SZ)" || { echo "❌ 计算结果.md 缺失或过小"; PASS=false; }
[ -f 程序/主程序.py ] && CSZ=$(wc -c < 程序/主程序.py) || CSZ=0
[ "$CSZ" -ge 500 ] && echo "✅ 程序/主程序.py ($CSZ)" || { echo "❌ 程序/主程序.py 缺失"; PASS=false; }
JSON_COUNT=$(ls 图表/*.json 2>/dev/null | wc -l)
[ "$JSON_COUNT" -ge 1 ] && echo "✅ 图表/*.json ($JSON_COUNT)" || { echo "❌ 图表/*.json 缺失"; PASS=false; }
# 子问题数对照: 建模报告里有几问, 程序/ 和 图表/ 就要有几份对应产出
EXPECTED_PROBS=$(grep -cE '^##\s*问题[一二三四五六七八九十0-9]|^###\s*问题[一二三四五六七八九十0-9]|^##\s*Problem\s*[0-9]' 建模报告.md 2>/dev/null || echo 0)
ACTUAL_CODE=$(ls 程序/problem*.py 2>/dev/null | wc -l)
ACTUAL_JSON=$(ls 图表/问题_*_结果.json 2>/dev/null | wc -l)
[ "$EXPECTED_PROBS" -gt 0 ] && {
[ "$ACTUAL_CODE" -ge "$EXPECTED_PROBS" ] || { echo "❌ 建模报告 $EXPECTED_PROBS 问, 但只有 $ACTUAL_CODE 个 problem*.py"; PASS=false; }
[ "$ACTUAL_JSON" -ge "$EXPECTED_PROBS" ] || { echo "❌ 建模报告 $EXPECTED_PROBS 问, 但只有 $ACTUAL_JSON 个 问题_*_结果.json"; PASS=false; }
}
[ "$PASS" != true ] && echo "⛔ 产出验证失败 — 必须补全所有缺失项后重新跑验证, 禁止 end_turn 结束本步骤"
```
## 工作过程
### 工作节点 0:恢复核验
核验 `计算结果.md`、`程序/*.py`、`图表/*_结果.json` 是否已出现:
- 计算结果.md 完整(>1KB)-> 跳到结果校验
- 程序/*.py 出现但无 计算结果.md -> 直接运行已有代码
- 什么都没有 -> 从头启动
### 工作节点 1:查阅建模报告 + 建立实现清单 + 防错复核
从 建模报告.md 提取各个子问题的求解算法、数学公式、输入交付标准、所需 Python 库。
**⛔ 防错复核(必做):** 查阅 `references/error_prevention_code.md`,依据 建模报告.md 末尾标注的题型,对照相应章节的"务必校验"和"常见 Bug"条目。编码过程中按项核验。
**⛔ MANDATORY: 交付实现清单,后续逐项打勾:**
```
IMPLEMENTATION CHECKLIST (from 建模报告.md):
[ ] 问题1: [算法名] — 输入: [xxx], 输出: [yyy], 库: [zzz]
[ ] 问题2: [算法名] — 输入: [xxx], 输出: [yyy], 库: [zzz]
[ ] 问题3: [算法名] — 输入: [xxx], 输出: [yyy], 库: [zzz]
[ ] 灵敏度分析: [参数列表]
```
每完成一个子问题,更新清单运行状态。
### 工作节点 1.5:提取图形与表格预规划
**⛔ MANDATORY: 查阅规划文档的图形与表格预规划,了解下一步 evidence-visualization 需产出哪些图形与表格。**
computational-realization 不产出 PDF 图形与表格,但需保证交付的 JSON 数据能支撑这些图形与表格。
```bash
echo "=== 图表预规划 ==="
for plan in 选题规划.md 问题分析.md 建模报告.md; do
[ -f "$plan" ] || continue
echo "--- $plan ---"
grep -i 'fig_\|图表\|TABLE_\|TikZ\|预规划\|figure' "$plan" | head -30
done
```
登记规划中的图形与表格清单,保证各个图形与表格相应的数据都会在分析过程中交付到 JSON。
**⛔ 图形与表格语言准则:** 中文论文(统计建模/数模竞赛)的图形与表格 axis label、legend、annotation 务必用中文。举例而言 `ax.set_xlabel('迭代次数')` 而不是 `ax.set_xlabel('Iterations')`。但这是 evidence-visualization 的事——computational-realization 只需保证 JSON 数据的 key 名有意义即可。
### 工作节点 2:环境准备
核验 Python,安装必要库(numpy, pandas, scipy, matplotlib, scikit-learn, statsmodels, networkx)。
### 工作节点 2.5:数据查阅校验(有附件数据时必做)
**⛔ 有数据时,写任何求解代码此前先完成独立的 `程序/data_preprocessing.py`;无数据时按明确豁免跳过:**
```python
# 程序/data_preprocessing.py — 数据审计、预处理与冻结输入(先跑这个,再写求解代码)
import pandas as pd
import os, glob
data_files = glob.glob('用户数据/*.csv') + glob.glob('用户数据/*.xlsx') + glob.glob('用户数据/*.xls')
print(f"找到 {len(data_files)} 个数据文件")
for f in data_files:
print(f"\n=== {os.path.basename(f)} ===")
try:
if f.endswith('.csv'):
# 尝试多种编码
for enc in ['utf-8', 'gbk', 'gb2312', 'latin-1']:
try:
df = pd.read_csv(f, encoding=enc)
print(f" 编码: {enc}")
break
except UnicodeDecodeError:
continue
else:
df = pd.read_excel(f)
print(f" 形状: {df.shape}")
print(f" 列名: {list(df.columns)}")
print(f" 数据类型:\n{df.dtypes}")
print(f" 缺失值:\n{df.isnull().sum()[df.isnull().sum() > 0]}")
print(f" 前3行:\n{df.head(3)}")
# 数值列的基本统计
num_cols = df.select_dtypes(include='number').columns
if len(num_cols) > 0:
print(f" 数值统计:\n{df[num_cols].describe()}")
# 检查异常值
for col in num_cols:
if df[col].min() < 0 and '价格' in col or '数量' in col or '距离' in col:
print(f" ⚠ {col} 有负值({df[col].min()}),检查是否合理")
if df[col].isnull().sum() > len(df) * 0.5:
print(f" ⚠ {col} 缺失率 > 50%")
except Exception as e:
print(f" ❌ 读取失败: {e}")
```
**实施 data_preprocessing.py 后,确认以下几点再继续:**
1. 全部数据文件都能无误查阅(编码、分隔符无误)
2. 列名和题目描述保持一致(不是乱码或错位)
3. 数据规模和题目描述保持一致(行数、列数)
4. 缺失值和异常值已识别,后续代码中有处理方案
5. 按 `建模报告.md` 的预处理合同完成实际变换,禁止只打印审计信息便结束
6. 处理前后质量统计均已计算,预测/学习任务已做到先划分、仅用训练集拟合变换器
7. 只生成一个供模型读取的规范文件到 `数据/processed/`,模型脚本不得回读 `用户数据/`
8. `全部结果.json.data_preparation` 已写入源文件与冻结输入 SHA-256、步骤、质量统计和泄漏控制
### 工作节点 3:代码目录结构
```
程序/
main.py # 主程序(串联所有子问题)
problem1.py # 子问题 1
problem2.py # 子问题 2
通用工具.py # 公共工具
依赖清单.txt
```
### 工作节点 3.0:⛔⛔⛔ 模块导入铁律(违反必失败)
**问题本质:** 程序/ 下的脚本互相 `import` 时,从不同目录调用会导致 sys.path 不涵盖 `程序/`,
报 `ModuleNotFoundError: No module named 'utils'` / `'problem1'` 等。这是历史上最高频的失败缘由。
**⛔ 准则 1:各个 .py 文件顶部务必有自举 import 头(在全部 import 此前):**
```python
# ⛔ 自举模块路径(让 sibling import 不依赖调用方式)
import os, sys
_HERE = os.path.dirname(os.path.abspath(__file__))
if _HERE not in sys.path:
sys.path.insert(0, _HERE)
# 之后才能写其它 import
import numpy as np
import 通用工具 as u # 现在 通用工具.py 跟当前文件同目录就一定能 import 到
```
**⛔ 准则 2:实施任何 程序/ 下的脚本务必 `cd code && python xxx.py`,禁止 `python 程序/xxx.py`**
```bash
# ✅ 正确(无论 utils 在不在都能跑)
cd code && python data_preprocessing.py && cd ..
cd code && python problem1.py && cd ..
cd code && python main.py && cd ..
# ❌ 错误:sys.path 不含 程序/,sibling import 会爆 ModuleNotFoundError
python 程序/problem1.py
python -m code.problem1
```
**⛔ 准则 3:写入子问题脚本前先写 `程序/通用工具.py` 雏形(哪怕暂时为空),避免"先写 problem1 → import utils → utils 还没建立"的瞬时错。**
**⛔ 准则 4:跑代码务必用 `set -e` + 明示核验 exit code,不可在脚本失败后假装结果有效:**
```bash
cd code
set -e
python data_preprocessing.py 2>&1 | tee ../临时文件/data_preprocessing.log
python problem1.py 2>&1 | tee ../临时文件/problem1.log
[ -f ../图表/问题_1_结果.json ] || { echo "❌ problem1 未产出结果 JSON"; exit 1; }
cd ..
```
### 工作节点 4:逐子问题编写和实施
**务必按次序逐问求解:编写 -> 实施 -> 校验 -> 下一问。**
**⛔ Phase 4.0: 上游一致性核验(启动编码前必做):**
```bash
echo "=== 上游一致性检查 ==="
# 检查 建模报告.md 是否存在
[ -f 建模报告.md ] && echo "✅ 建模报告.md 存在" || { echo "❌ 建模报告.md 不存在!"; exit 1; }
# 提取子问题数量
PROB_COUNT=$(grep -c '问题[一二三四五六七八九十0-9]' 问题分析.md 2>/dev/null || echo 0)
MODEL_COUNT=$(grep -c '问题[一二三四五六七八九十0-9]' 建模报告.md 2>/dev/null || echo 0)
echo "问题情境解构子问题数: $PROB_COUNT, 建模报告子问题数: $MODEL_COUNT"
[ "$MODEL_COUNT" -lt "$PROB_COUNT" ] && echo "⚠ 建模报告覆盖的子问题数少于问题情境解构,请检查是否遗漏"
# 提取建模报告推荐的方法
echo "--- 建模报告推荐方法 ---"
grep -i '算法\|方法\|模型.*选择\|求解.*策略' 建模报告.md 2>/dev/null | head -10
echo "--- 计算实验实现时必须使用上述方法,或明确说明替代理由 ---"
```
代码性能要求:
- 优先采用 numpy 向量化运算,避免 Python 原生 for 循环遍历大数据
- 数据量大(>1000 行)务必用向量化或矩阵运算
- 各个脚本实施前后打印进度信息
- 若代码跑超过 3 分钟,立即重写优化版本
自主判定数据来源:
- 有附件数据(`用户数据/*.csv` 出现):从文件查阅
- 无附件数据(纯建模题):依据 建模报告.md 自行构造参数
各个子问题:
1. 编写独立 Python 文件
2. 实施并核验交付
3. 校验结果合理性
4. 留存结果到 `图表/问题_N_结果.json`
5. 结果异常则调整代码重跑
---
### 工作节点 4.5:⛔⛔⛔ 每问跑完后的自检过程(关键,各个子问题都务必做)
**这是当前环节防失败的关键。每完成一问的代码 + JSON 后,务必按下面过程做自检,
满足要求才能转入下一问。** 避免写完全部问题再统一自检 — 那样发现问题要回头改, 浪费 turn 预算。
各个子问题跑完, 立即按以下次序 Read 自检文件并按其要求校验:
**第 1 步:必读(全部题型)**
```
Read references/checks/_index.md # 自检总索引(仅第 1 问读, 后续可跳过)
Read references/checks/consistency.md # 建模-代码契约 + 物理参数引用 + 自动化约束验证代码
Read references/checks/sanity_check.md # 自动数值审查 + 9 问背景审查 + 编程 Bug 排查
```
**第 2 步:依据本问的题型选读 1 个分类自检文件**
| 本问类别 | Read 哪个 |
|---|---|
Auf GitHub ansehen