simulation-validator

Simulation Validator

目标

为材料模拟提供三阶段验证流程：运行前检查、运行时监控和运行后验证。

要求

• Python 3.10+
• 无外部依赖（仅使用 Python 标准库）
• 适用于 Linux、macOS 和 Windows

需要收集的输入

运行验证脚本前，请向用户收集以下信息：

输入	描述	示例
配置文件	模拟配置（JSON/YAML）	simulation.json
日志文件	运行时输出日志	simulation.log
指标文件	运行后的指标（JSON）	results.json
必需参数	必须存在的参数	dt,dx,kappa
有效范围	参数范围	dt:1e-6:1e-2

决策指南

各阶段的运行时机

Is simulation about to start?
├── YES → Run Stage 1: preflight_checker.py
│         └── BLOCK status? → Fix issues, do NOT run simulation
│         └── WARN status? → Review warnings, document if accepted
│         └── PASS status? → Proceed to run simulation
│
Is simulation running?
├── YES → Run Stage 2: runtime_monitor.py (periodically)
│         └── Alerts? → Consider stopping, check parameters
│
Has simulation finished?
├── YES → Run Stage 3: result_validator.py
│         └── Failed checks? → Do NOT use results
│                            → Run failure_diagnoser.py
│         └── All passed? → Results are valid

选择验证阈值

指标	保守	标准	宽松
质量容差	1e-6	1e-3	1e-2
残差增长	2x	10x	100x
dt 缩减	10x	100x	1000x

脚本输出（JSON 字段）

脚本	输出字段
scripts/preflight_checker.py	report.status、report.blockers、report.warnings
scripts/runtime_monitor.py	alerts、residual_stats、dt_stats（警报包括 NaN/Inf/溢出检测、残差增长和 dt 崩溃）
scripts/result_validator.py	checks、confidence_score、failed_checks、status（PASS / FAIL / INSUFFICIENT_DATA）；若未运行任何检查，confidence_score 为 null
scripts/failure_diagnoser.py	probable_causes、recommended_fixes

三阶段验证流程

阶段 1：运行前（模拟开始前）

1. 运行 scripts/preflight_checker.py --config simulation.json
2. BLOCK 状态：立即停止，修复所有阻止问题
3. WARN 状态：查看警告，并记录已接受的风险
4. PASS 状态：继续运行模拟

注意：preflight_checker.py 会验证必需键、数值范围、输出目录的访问权限和磁盘空间。它不会评估数值稳定性（CFL / diffusion-Fourier）。如需基于显式稳定性进行判定，请使用 skills/core-numerical/numerical-stability/scripts/cfl_checker.py。

python3 scripts/preflight_checker.py \
    --config simulation.json \
    --required dt,dx,kappa \
    --ranges "dt:1e-6:1e-2,dx:1e-4:1e-1" \
    --min-free-gb 1.0 \
    --json

阶段 2：运行时（模拟期间）

1. 定期运行 scripts/runtime_monitor.py --log simulation.log
2. 根据问题类型配置警报阈值
3. 出现严重警报时停止模拟

python3 scripts/runtime_monitor.py \
    --log simulation.log \
    --residual-growth 10.0 \
    --dt-drop 100.0 \
    --json

阶段 3：运行后（模拟结束后）

1. 运行 scripts/result_validator.py --metrics results.json
2. 所有检查均 PASS：结果可用于分析
3. 任意检查 FAIL：不要使用结果，应诊断故障

python3 scripts/result_validator.py \
    --metrics results.json \
    --bound-min 0.0 \
    --bound-max 1.0 \
    --mass-tol 1e-3 \
    --json

对于变分 / 梯度流模型（Allen-Cahn、Cahn-Hilliard），添加 --variational 以强制检查能量严格单调不增。

故障诊断

验证失败时：

python3 scripts/failure_diagnoser.py --log simulation.log --json

对话工作流示例

用户：我的相场模拟运行了 1000 步后崩溃了。你能帮我找出原因吗？

Agent 工作流：

1. 首先，检查日志中是否有明显错误：

   python3 scripts/failure_diagnoser.py --log simulation.log --json
   

2. 如果诊断结果显示数值发散，请检查运行时统计信息：

   python3 scripts/runtime_monitor.py --log simulation.log --json
   

3. 根据发现的问题提出修复建议：
   • 如果残差快速增长 → 减小时间步长
   • 如果 dt 崩溃 → 检查稳定性条件
   • 如果检测到 NaN → 检查初始条件

错误处理

错误	原因	解决方法
Config not found	文件路径无效	确认配置文件路径存在
Non-numeric value	参数不是数字	修正配置文件格式
out of range	参数超出范围	调整参数或范围
Output directory not writable	权限问题	检查目录权限
Insufficient disk space at <path>	输出卷上的磁盘空间即将耗尽	释放空间或减少输出
Invalid parameter name	--required 名称含有不允许的字符	仅使用字母、数字、_、.、-
range max ... must be greater than min	--ranges 或边界设置反向或退化	确保 max > min
must be a finite positive number	提供了 nan/inf/负数阈值	传入有限的正数值
Log file too large	日志超过 500 MB 的解析上限	截断日志或预先过滤

结果解读指南

状态含义

状态	含义	操作
PASS	所有检查均已通过	放心继续
WARN	发现非关键问题	检查并记录
BLOCK	发现关键问题	必须修复后才能继续

置信度分数解读

分数	含义
1.0	所有验证检查均已通过 → 放心继续
0.75+	大多数检查已通过，存在轻微问题
0.5-0.75	存在显著问题，请仔细检查
< 0.5	存在重大问题，请勿信任结果
null（状态为 INSUFFICIENT_DATA）	没有可识别的指标字段；未运行任何检查——这不代表通过。请检查指标文件。

如果指标中没有与请求的边界（--bound-min/--bound-max）匹配的 field_min/field_max，系统会将其报告为失败的 bounds_unverifiable 检查，而不会将其视为通过。 对于变分/梯度流运行，请传入 --variational（或在指标中设置 "energy_variational": true），以强制执行严格的单调非增能量检查（energy_monotone）；否则会使用较宽松的 energy_net_decrease 检查，该检查无法检测运行过程中的能量突增。

常见故障模式

日志中的模式	可能原因	建议修复方法
NaN、Inf、溢出	数值不稳定	减小 dt，增大阻尼
达到最大迭代次数，未收敛	求解器故障	调整预条件器和容差
内存不足	内存耗尽	减小网格，启用外存模式
dt 减小	触发了自适应步进	如果受控，可能没有问题

验证清单

在满足下方所有适用项，并确认其中列出的具体产物之前，不要轻信验证结论。 请在向用户提供的摘要中记录这些信息。

• 运行了 result_validator.py --json，并确认 results.status 为 PASS（而非 INSUFFICIENT_DATA），且 results.confidence_score == 1.0；分数为 null 或状态为 INSUFFICIENT_DATA 表示未运行检查——应视为未经验证，而非通过。
• 列出了 results.checks，并确认其中实际包含所有请求的检查（例如 mass_conserved、bounds_satisfied、no_nan 和 energy_monotone/energy_net_decrease）；确认 results.failed_checks 为空，且其中不包含 bounds_unverifiable 条目（这意味着请求的边界没有可供比较的 field_min/field_max）。
• 对于变分/梯度流模型（Allen-Cahn、Cahn-Hilliard），传入了 --variational（或设置 "energy_variational": true），以强制执行 energy_monotone；记录未依赖较弱的 energy_net_decrease，因为它无法检测运行中途的能量尖峰。
• 记录了使用的质量漂移容差（--mass-tol，默认值为 1e-3），并确认其与本次运行适用的 Conservative/Standard/Relaxed 列相符；对于严格守恒问题，没有默默接受默认值。
• 运行了 runtime_monitor.py --json 并记录了 residual_stats（最小值/最大值/最后值）和 dt_stats；确认没有针对 NaN/Inf/溢出、残差增长超过 --residual-growth 或 dt 降至 --dt-drop 以下的 alerts。
• 确认通过 core-numerical/numerical-stability/scripts/cfl_checker.py 单独把关数值稳定性（CFL/Fourier 限制）——preflight_checker.py 不评估 CFL/Fourier，因此预检通过并不代表时间/空间稳定。
• 若出现任何 FAIL 或警报，运行了 failure_diagnoser.py --json 并记录 probable_causes/recommended_fixes，而不是重复使用原有结果。

常见误区与自我安慰

看似省事的做法	错误之处 / 应采取的做法
“预检通过了，所以运行在数值上是稳定的。”	preflight_checker.py 只检查必需键、取值范围、输出目录是否可写以及磁盘空间。它不计算 CFL/Fourier。应单独使用 cfl_checker.py 把关稳定性。
“result_validator 输出了置信度分数，所以结果没问题。”	空指标文件或无法识别的指标文件会返回 confidence_score: null 和状态 INSUFFICIENT_DATA——这表示“未运行检查”，而不是通过。请确认存在可识别的字段，且 status == PASS。
“能量最终低于初始值，所以耗散运行没问题。”	默认的 energy_net_decrease 只比较首尾值，会漏掉运行中途的尖峰。对于梯度流模型，使用 --variational 强制执行严格的单调性检查 energy_monotone。
“我要求检查边界，结果没有出现 bounds_satisfied: false，所以边界符合要求。”	如果缺少 field_min/field_max，验证器会输出 bounds_unverifiable（检查失败），而不会无条件判定通过。请确保指标文件确实包含场变量极值。
“仿真顺利结束，没有崩溃，所以结果可信。”	运行完成不等于结果正确。使用结果前，请验证质量守恒、能量变化、物理边界，并确认 runtime_monitor 的警报列表为空。
“运行期间 dt 变小了，所以求解器出问题了。”	runtime_monitor 的 dt 下降检测会根据变化方向（运行最大值与当前值）进行判断，并且只有超过 --dt-drop 才会报警；受控的自适应递增是预期行为。请检查实际的 dt_stats，以及是否触发了警报。
“我直接使用默认阈值就行。”	默认值（--mass-tol 1e-3、--residual-growth 10、--dt-drop 100）对应 Standard 列；对守恒要求严格的问题，应使用 Conservative 容差。请根据物理问题选择阈值并记录下来。

安全

输入验证

• 解析前会验证配置文件路径是否存在；路径不存在时会显示明确错误（退出代码为 2）
• --required 参数名会根据安全字符白名单（^[A-Za-z0-9_.-]+$）进行验证；包含 Shell 元字符的名称会被拒绝
• --ranges 条目会按 name:min:max 解析，要求数值上下限为有限值，且 max > min
• --min-free-gb 会验证为有限正数（拒绝负数、零、nan、inf）
• --residual-growth 和 --dt-drop 阈值会验证为有限正数
• --bound-min 和 --bound-max 会验证为有限数值（拒绝 nan/inf），并强制要求 --bound-max > --bound-min；--mass-tol 会验证为有限正数
• 输入无效时会以代码 2 退出，并显示说明性消息

文件访问

• preflight_checker.py 会读取一个用户指定的配置文件（JSON/YAML），并检查存放已解析输出目录的卷上的磁盘空间
• runtime_monitor.py 会读取 --log 指定的单个日志文件；日志文件大小上限为 500 MB，超过上限时会在解析前拒绝读取
• result_validator.py 会读取 --metrics 指定的单个指标文件（JSON）
• failure_diagnoser.py 会读取 --log 指定的单个日志文件；日志文件会在解析前受 500 MB 的大小限制
• 脚本不会写入文件系统；所有输出均发送到 stdout

工具限制

• Read：用于检查脚本源代码、参考资料、配置文件和模拟日志
• Bash：用于通过显式参数列表执行四个 Python 验证脚本（preflight_checker.py、runtime_monitor.py、result_validator.py、failure_diagnoser.py）
• Write：用于保存验证报告；写入范围限定在用户的工作目录内
• Grep/Glob：用于查找日志文件、配置文件和搜索参考资料

安全措施

• 不使用 eval()、exec() 或动态代码生成
• 所有子进程调用都使用显式参数列表（不使用 shell=True）
• failure_diagnoser.py 使用硬编码的预编译诊断正则表达式；runtime_monitor.py 接受可选的 --residual-pattern / --dt-pattern 覆盖项，并使用 re.compile 编译（不使用 eval），且仅应用于用户自己的日志
• 输出中的诊断字符串取自技能固定的原因/修复表，不会通过原始日志内容插值生成

局限性

• 不是实时监控工具：脚本会在事后分析日志
• 基于正则表达式：日志解析依赖模式匹配，可能无法识别不常见的格式
• 不提供自动修复：脚本会诊断问题，但不会修改模拟

参考资料

• references/validation_protocol.md - 详细的检查清单和标准
• references/log_patterns.md - 常见故障特征和正则表达式模式

版本历史

• v1.2.2（2026-06-24）：添加了验证检查清单（基于证据，并关联四个脚本的 JSON 输出）和常见陷阱与合理化说辞表，以强化 Agent 对验证结论的解读。
• v1.2.0（2026-06-23）：修正诊断正则表达式（避免将正常日志误判为收敛/失控），检测步长坍缩时考虑方向，在运行时监控中扫描 NaN/Inf，严格检查变分能量，确保边界/置信度检查非空洞，配置相对输出目录并检查正确卷上的磁盘空间，以及实现文档所述的输入验证/文件大小保护措施
• v1.1.0（2024-12-24）：增强文档、决策指导和 Windows 兼容性
• v1.0.0：首次发布，包含 4 个验证脚本