parameter-optimization

参数优化

目标

提供一种工作流，用于设计实验、评估参数影响并选择材料模拟校准的优化策略。

要求

• Python 3.10+
• 无外部依赖（仅使用 Python 标准库）

需要收集的输入

运行任何脚本前，请先向用户收集以下信息：

输入	描述	示例
参数范围	每个参数的最小值/最大值及单位	kappa: [0.1, 10.0] W/mK
评估预算	允许的最大模拟次数	50 runs
噪声水平	模拟输出的随机性	低、中、高
约束条件	可行性规则或禁用区域	kappa + mobility < 5

决策指南

选择 DOE 方法

Is dimension <= 3 AND full coverage needed?
├── YES → Use factorial
└── NO → Is sensitivity analysis the goal?
    ├── YES → Use quasi-random (preferred; "sobol" is accepted but deprecated)
    └── NO → Use lhs (Latin Hypercube)

方法	最适用于	避免使用的情况
lhs	一般探索、中等维度（3-20）	需要精确覆盖网格
quasi-random	敏感性分析、均匀覆盖（首选）	维度非常高（>20）
sobol	已弃用的 quasi-random 别名（会发出警告）	新代码（请使用 quasi-random）
factorial	低维（<4）、需要覆盖所有角点	高维（呈指数增长）

因子设计采样数： 因子网格为每个参数生成 levels 个均匀分布的值，恰好产生 levels ** params 个样本。使用 --levels 显式设置分辨率（例如 --params 2 --levels 4 -> 16 个样本）。如果改用 --budget，脚本会反向计算 levels = round(budget ** (1/params))，并在实际采样数与请求预算不同时发出警告（例如 --budget 20 --params 2 实际生成 16 个样本）。如需精确的设计，请传入完全幂次（--budget 16），或优先使用 --levels。

选择优化器

Is dimension <= 10 AND budget <= 100?
├── YES → Bayesian Optimization
└── NO → Is dimension <= 20?
    ├── YES → CMA-ES
    └── NO → Random Search with screening

噪声水平	建议
低	有可用导数时使用基于梯度的方法，否则使用贝叶斯优化
中	使用带噪声模型的贝叶斯优化
高	使用进化算法或稳健贝叶斯优化

脚本输出（JSON 字段）

脚本	输出字段
scripts/doe_generator.py	samples、method、coverage（count、dimension；因子设计还包括 levels 和顶层的 requested_budget/note）
scripts/optimizer_selector.py	recommended、expected_evals、notes
scripts/sensitivity_summary.py	ranking、notes
scripts/surrogate_builder.py	model_type、metrics（mse、cv_error、output_variance）、notes

工作流

1. 使用 scripts/doe_generator.py 生成 DOE
2. 在 DOE 样本点上运行模拟（由用户负责）
3. 使用 scripts/sensitivity_summary.py 汇总敏感性
4. 使用 scripts/optimizer_selector.py 选择优化器
5. （可选） 使用 scripts/surrogate_builder.py 拟合代理模型

CLI 示例

# Generate 20 LHS samples for 3 parameters
python3 scripts/doe_generator.py --params 3 --budget 20 --method lhs --json

# Full factorial with 4 levels per parameter (2 params -> 16 samples)
python3 scripts/doe_generator.py --params 2 --levels 4 --method factorial --json

# Rank parameters by sensitivity scores
python3 scripts/sensitivity_summary.py --scores 0.2,0.5,0.3 --names kappa,mobility,W --json

# Get optimizer recommendation for 3D problem with 50 eval budget
python3 scripts/optimizer_selector.py --dim 3 --budget 50 --noise low --json

# Build surrogate model from simulation data
python3 scripts/surrogate_builder.py --x 0,1,2 --y 10,12,15 --model rbf --json

对话式工作流示例

用户：我需要校准 FEM 模拟中的热导率和热扩散率。大约可以运行 30 次模拟。

Agent 工作流：

1. 确定有 2 个参数 → --params 2
2. 预算为 30 → --budget 30
3. 使用 LHS 进行一般探索：

   python3 scripts/doe_generator.py --params 2 --budget 30 --method lhs --json
   

4. 用户运行模拟并提供输出后，汇总敏感性：

   python3 scripts/sensitivity_summary.py --scores 0.7,0.3 --names conductivity,diffusivity --json
   

5. 推荐优化器：

   python3 scripts/optimizer_selector.py --dim 2 --budget 30 --noise low --json
   

错误处理

错误	原因	解决方法
params must be positive	维度为零或负数	请用户提供有效的参数数量
budget must be positive	预算为零或负数	请用户提供合理的模拟预算
argument --method: invalid choice: <value> (choose from lhs, sobol, quasi-random, factorial)	方法无效（argparse）	根据决策指南选择有效方法
could not convert string to float: <token>	--scores/--x/--y 中包含非数值	重新格式化为 0.1,0.2,0.3
scores must be a comma-separated list	--scores 输入为空	至少提供一个数值分数

验证清单

• 记录 doe_generator.py 的确切 coverage.count，并确认其与预期设计一致——对于 factorial，验证 count == levels ** params，且未发出 note/requested_budget 不匹配警告（或实际样本数可接受）。
• 确认所选 --method 符合实际维度/目标对应的决策指南，并确认使用了 quasi-random，而不是已弃用的 sobol 别名（输出中没有 DeprecationWarning）。
• 记录 optimizer_selector.py 的 recommended 策略和 expected_evals，并验证 expected_evals <= budget，确保计划符合所述评估预算。
• 记录 sensitivity_summary.py 的 ranking，并检查最高灵敏度是否 < 0.1（即出现“所有灵敏度都较低”的提示）；如果是，则不要过度解读排名，并重新审视输出指标。
• 对于代理模型拟合，使用 metrics.cv_error（留一法）而非样本内 mse 来评估质量——尤其是 rbf，其 mse 按构造几乎为零——并将 cv_error 与 metrics.output_variance 比较，以确认代理模型优于常数均值基线。
• 确认报告的任何 cv_error 都是有限数值（不是 NaN），即有足够的样本用于留一法（poly：n > degree+1；rbf：n >= 3）。

常见陷阱与自我辩解

看似省事的做法	错误原因 / 应采取的做法
“RBF 代理模型的 mse 约为 0，所以模型非常出色。”	RBF 是精确插值器——按构造，样本内 mse 几乎为零，无法说明泛化能力。应使用 metrics.cv_error 评估拟合效果，并将其与 output_variance 比较。
“我指定了 --budget 20 的 factorial，所以得到了 20 个样本。”	Factorial 遵循 levels ** params，而非预算；--budget 20 --params 2 实际生成 16 个样本，并发出 note/警告。要获得精确且符合预期的设计，请使用 --levels。
“sobol 会生成真正的 Sobol 低差异序列。”	sobol 是已弃用的别名，会发出 DeprecationWarning，并使用简化的黄金比例加法递推，而非真正的 Sobol 序列。请使用 quasi-random；如需在生产环境中使用 Sobol，请使用 scipy.stats.qmc。
“优化器的建议只是参考——预算无关紧要。”	建议取决于维度和预算（只有 dim<=10 AND budget<=100 时才使用 BO），且 expected_evals 不会超过预算。请记录两者，并确认计划符合实际预算。
“一个灵敏度分数最高，所以该参数影响最大。”	脚本只会对你传入的分数排序；它本身不会计算灵敏度。如果最高分 < 0.1，脚本会提示所有灵敏度都较低——在相信排名前，请通过真实的筛选分析/Sobol 分析获取分数。
“它输出了 JSON，且没有报错，所以结果有效。”	成功退出只表示输入已解析。信任任何输出前，请验证设计规模、expected_evals <= budget、cv_error 为有限值，并确认代理模型优于 output_variance。

安全

输入验证

• sensitivity_summary.py 使用 [a-zA-Z_][a-zA-Z0-9_ .-]* 验证 --names，并限制长度为 200 个字符，防止通过精心构造的参数名称注入 Shell 元字符
• 所有数值列表输入都会验证是否为有限数值（拒绝 NaN/Inf）
• 逗号分隔的值列表设有上限（分数为 10,000 个，代理数据为 100,000 个），以防资源耗尽
• doe_generator.py 将维度上限设为 1,000、预算上限设为 1,000,000；optimizer_selector.py 将维度上限设为 100,000、预算上限设为 10,000,000
• --method 会根据固定的允许列表进行验证（lhs、quasi-random/sobol）；sobol 是可接受但已弃用的 quasi-random 别名
• --noise 会根据固定的允许列表进行验证（low、medium、high）
• --model（代理类型）会根据固定的允许列表进行验证（rbf、poly）
• --levels（因子设计网格分辨率）会验证是否为 [2, 1000] 范围内的整数

文件访问

• 脚本不会读取外部文件；所有输入均通过 CLI 参数提供
• 脚本只向 stdout 写入内容（JSON 输出）；除非 Agent 明确使用 Write 工具，否则不会创建文件

工具限制

• Read：用于检查脚本源代码、参考资料和用户数据文件
• Write：用于保存 DOE 样本计划、敏感性排序或优化器建议；写入范围限定在用户的工作目录内
• Grep/Glob：用于定位相关文件和搜索参考资料
• 该技能的 allowed-tools 不包含 Bash，以防 Agent 在处理用户提供的参数名称和约束时执行任意命令

安全措施

• 不使用 eval()、exec() 或动态代码生成
• 所有子进程调用均使用显式参数列表（不使用 shell=True）
• 缩小工具范围（不提供 Bash）将 Agent 限制为仅执行读写操作
• 参数名称在使用前会经过清理，防止通过精心构造的标识符进行注入

局限性

• 不适用于实时优化：脚本提供建议，而非实时优化循环
• 代理模型较轻量：surrogate_builder.py 仅使用标准库拟合真实的 1-D 最小二乘多项式（poly）或高斯 RBF 插值函数（rbf），并如实报告残差 mse、留一法 cv_error 和数据的 output_variance；生产环境中请使用 scipy/scikit-learn/GPyTorch。对于 rbf，根据构造，样本内 mse 接近零（精确插值）——请使用 cv_error 判断拟合质量
• 不会自动执行仿真：用户必须在外部运行仿真并提供结果

参考资料

• references/doe_methods.md - DOE 方法详细比较
• references/optimizer_selection.md - 优化算法详情
• references/sensitivity_guidelines.md - 敏感性分析结果解读
• references/surrogate_guidelines.md - 代理模型选择

版本历史

• v1.2.2（2026-06-24）：新增验证清单和常见陷阱及其合理化解释章节，推动基于证据使用 DOE、优化器、敏感性和代理模型脚本
• v1.2.0（2026-06-23）：新增真实代理模型拟合（poly 最小二乘、rbf 插值），如实报告 mse/cv_error/output_variance；新增显式因子设计 --levels 参数及预算不匹配警告；将 BO 维度上限统一为 dim<=10；修正文档中的安全、错误处理和输出字段说明，使其与脚本行为一致
• v1.1.0（2024-12-24）：增强文档、决策指南和对话示例
• v1.0.0：初始版本，包含核心脚本