benchmark-and-mms-planner

基准测试与 MMS 规划器

目标

在信任仿真结果之前，设计验证与确认计划。该技能可帮助 Agent 选择制造解、基准测试案例、细化方案、不确定性检查及通过／失败标准。

要求

• Python 3.10+
• 无外部依赖
• 适用于 Linux、macOS 和 Windows

需要收集的输入

输入	说明	示例
PDE 或模型类别	控制方程所属类别	diffusion、elasticity、phase-field
关注量	要验证的指标	interface velocity、L2 temperature error
维度	1、2 或 3	2
预期阶数	离散格式的形式阶数	2
参考结果可用性	解析解、基准测试或无	analytic
风险级别	错误结果造成的成本或后果	high

决策指南

• 当代码正确性不确定且可以注入解析解时，使用 MMS。
• 当物理模型验证比代码验证更重要时，使用 标准基准测试。
• 只要结果用于主张、设计决策或比较，就进行 网格／时间细化。
• 当输入经过校准、带有噪声或通过实验测得时，进行 不确定性传播。

脚本输出

scripts/benchmark_mms_planner.py 会生成包含 inputs 和 results 的输出，其中包括：

• verification_strategy
• effective_model — 实际使用的解析后模型类别；未知类别会回退为 general。
• mms_plan
• benchmark_cases
• refinement_protocol（dimension、levels、spacing_ratio、expected_order、accept_observed_order_min、include_time_refinement）
• uncertainty_plan（propagate_inputs、report_error_bars、separate_discretization_and_model_error）— 根据风险级别和参考类型提供传播／误差条建议。
• acceptance_criteria
• warnings

accept_observed_order_min 是一种工程筛查启发式指标，并非经过认证的界限：它将形式上的 expected_order 按比例容差下调（高风险为 10%，其他情况为 20%），并以一阶收敛（1.0）为下限。相对范围可确保不同形式阶数下的严格程度一致。参见 references/vv_patterns.md。

工作流

1. 收集控制模型、关注量和风险级别。
2. 运行 benchmark_mms_planner.py --json。
3. 对于高风险主张，将警告视为阻断项。
4. 将返回的方案转化为测试、仿真运行或审查清单项。

python3 skills/verification-validation/benchmark-and-mms-planner/scripts/benchmark_mms_planner.py \
  --model diffusion \
  --quantity "L2 error in temperature" \
  --dimension 2 \
  --expected-order 2 \
  --reference analytic \
  --risk high \
  --json

错误处理

• 如果维度或预期阶数无效，请停止并更正模型描述。
• 如果没有参考结果，请使用守恒性和收敛性检查，但不要将结果称为已验证。

局限性

此技能用于规划验证工作；它不会运行求解器，也无法证明某个物理模型适用于某项实验。

验证清单

在信任使用此规划器得到的结果之前，请为每一项记录具体证据：

• 运行了 benchmark_mms_planner.py --json 并保存了 inputs 块，确认回显的 dimension、expected_order、reference 和 risk 与实际运行相符（回退到 effective_model: general 是有意为之，而不是 --model 拼写错误）。
• 执行了 refinement_protocol：使用报告的 levels（3；高风险时为 4）进行系统性网格细化，且 spacing_ratio 为 2，并记录这些运行中观测到的精度阶数。
• 确认观测到的阶数不低于 accept_observed_order_min；如果低于该值，应记录调查情况（网格尚未进入渐近区间、边界/源项误差、限制器激活），而不是将结果视为通过。
• 当 include_time_refinement 为 true 时，单独进行了时间步长细化研究，并记录时间观测阶数，而不只是空间观测阶数。
• 当 mms_plan.manufacture_solution 为 true 时，推导了符号源项/强迫项，应用了匹配的边界项，并记录相对于制造解的 L2 和 Linf 误差范数。
• 用数值核查每一项 acceptance_criteria：守恒/平衡在有记录的容差范围内闭合，关注量在细化过程中趋于稳定，并在投入生产使用前解释 benchmark_cases 中的任何基准差异。
• 将 warnings 中的所有条目都视为高风险声明的阻碍，并记录每项警告的解决方式（例如，当 reference 为 none 或 experimental 时，补充独立的解析参考或已发表的参考）。

常见陷阱与自我安慰

看似省事的做法	错误原因 / 应采取的做法
“规划器运行并打印了计划，所以结果已经验证。”	脚本只负责 规划 V&V；它不会运行求解器。验证来自执行 refinement_protocol、MMS 和 acceptance_criteria，而非生成计划。
“两个网格已经收敛，所以观测阶数没问题。”	refinement_protocol.levels 设为 3（高风险时为 4）是有原因的：需要至少 3 个系统性细化的网格来估算观测阶数，并确认解处于渐近区间后才能报告该阶数。
“观测阶数高于 accept_observed_order_min，所以结果已获认证。”	该阈值是工程上的 筛查 启发式标准（形式阶数减去 10%/20% 的相对容差，且下限为 1.0），并非经过认证的界限。要严格验证阶数，请进行 Richardson/GCI 研究。
“模型看起来是稳态的，所以可以跳过 include_time_refinement。”	如果规划器将 include_time_refinement: true 设为真（任何时变或 general 回退模型族），仅进行空间细化会掩盖时间误差；还要进行时间步长研究。
“我们与一个基准匹配了，所以代码已经验证。”	匹配 benchmark_cases 或达到收敛，只能说明代码趋近于 某个 解；这并不能证明物理模型正确。验证需要独立参考并区分模型误差，不能只看收敛。
“reference none 没问题，运行结果看起来符合物理规律。”	当 reference: none 时，策略仅用于验证；warnings 已说明这一点。可以报告收敛性和守恒性，但绝不能称结果已通过确认。
“模型名称未知，所以我会忽略 general 回退。”	无法识别的 --model 会静默解析为 effective_model: general；请确认此回退符合预期，因为它会同时改变 benchmark_cases 和时间细化的决策。

安全

输入验证

所有输入均为由 argparse 解析的命令行参数；验证在 plan_vv 中进行（部分验证也在解析器中进行）。任何被拒绝的输入都会使脚本将错误输出到 stderr，并以代码 2 退出。

• dimension 必须恰好为 1、2 或 3；其他任何整数都会被拒绝。
• expected_order 必须是正的有限数值（NaN、无穷大、零和负数都会被拒绝）。
• risk 必须是允许列表 low、medium、high 中的一项（由 argparse 选项强制执行，并在 plan_vv 中再次检查）。
• reference 必须是允许列表 analytic、benchmark、experimental、none 中的一项（由 argparse 选项强制执行，并在 plan_vv 中再次检查）。
• model 和 quantity 的长度上限为 256 个字符（MAX_FIELD_LEN）；更长的字符串会被拒绝。
• 除此之外，model 和 quantity 的字符串内容不受允许列表限制，也不会经过净化：quantity 会原样回显到输出中，而无法识别的 model 系列会被静默解析为 general，不会被拒绝。

文件访问

• 脚本不会读取或写入任何文件；所有 I/O 都是命令行参数 -> stdout JSON（或简短的纯文本摘要），错误则输出到 stderr。
• 脚本不接受或构造文件系统路径，因此不存在路径遍历攻击面，也不需要路径沙箱逻辑。
• 唯一与 DoS 相关的大小限制是 model 和 quantity 的 256 个字符上限；数值输出受已验证输入的范围限制。

工具限制

Frontmatter 声明了 allowed-tools: Read, Bash, Write, Grep, Glob。

• Bash 仅用于运行随附的 scripts/benchmark_mms_planner.py（例如工作流中的 python3 ... --json 调用）。
• 在规划时，Read、Grep 和 Glob 用于检查技能自身的文件和参考资料（例如 references/vv_patterns.md）。
• Write 可用于将返回的协议转成测试桩或清单文件；规划器脚本本身不会写入文件。

安全措施

• 不使用 eval、exec 或动态代码执行；规划器是一个纯 Python 程序，用于计算字典。
• 脚本不会启动子进程，也不会调用外部求解器，因此不存在需要转义的子进程参数列表。
• 不会使用 pickle 或其他方式反序列化不可信数据；输出使用 json.dumps 序列化。
• 256 个字符的字段上限是针对异常长输入字符串的明确 DoS 防护措施。

参考资料

• MMS、基准测试和不确定性规划说明请参阅 references/vv_patterns.md。

版本历史

• 1.1.3：新增“验证清单”（基于证据，涉及规划器的 refinement_protocol、mms_plan、acceptance_criteria 和 warnings），并新增 “常见陷阱与合理化说辞”表格，明确界定领域特定的 V&V 捷径（规划 != 验证、计算观测阶至少需要 3 个网格、筛查区间不是经认证的界限、时间加密、收敛 != 验证、reference none、 general 回退）。
• 1.1.1：添加确定性的 script_checks，针对每种情形固定规划器的具体输出（解析后的 verification_strategy、相对的 accept_observed_order_min 区间、加密 levels、 include_time_refinement、uncertainty_plan 标志、模型特定的基准测试用例，以及准确的警告字符串），使评估套件更具区分度。
• 1.1.0：将未知模型系列统一解析为 general，确保基准测试选择和时间加密决策一致（未列出的瞬态 PDE 不再跳过时间加密）； 将解析后的系列作为 effective_model 回显。将固定的绝对观测阶偏移量替换为以一阶为下限的相对容差。记录 uncertainty_plan、 effective_model 和验收启发式。为字符串输入添加 256 个字符的长度上限。
• 1.0.0：初始基准测试和 MMS 规划技能。