parameter-optimization

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Parameter Optimization

参数优化

Goal

目标

Provide a workflow to design experiments, rank parameter influence, and select optimization strategies for materials simulation calibration.

提供一个用于材料模拟校准的实验设计、参数影响排序及优化策略选择的工作流。

Requirements

要求

Python 3.10+
No external dependencies (uses Python standard library only)

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

Inputs to Gather

需要收集的输入信息

Before running any scripts, collect from the user:

Input	Description	Example
Parameter bounds	Min/max for each parameter with units	`kappa: [0.1, 10.0] W/mK`
Evaluation budget	Max number of simulations allowed	`50 runs`
Noise level	Stochasticity of simulation outputs	`low` , `medium` , `high`
Constraints	Feasibility rules or forbidden regions	`kappa + mobility < 5`

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

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

Decision Guidance

决策指南

Choosing a DOE Method

选择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)

Method	Best For	Avoid When
`lhs`	General exploration, moderate dimensions (3-20)	Need exact grid coverage
`quasi-random`	Sensitivity analysis, uniform coverage (preferred)	Very high dimensions (>20)
`sobol`	Deprecated alias of `quasi-random` (emits a warning)	New code (use `quasi-random` )
`factorial`	Low dimension (<4), need all corners	High dimension (exponential growth)

Factorial sizing: the factorial grid is
levels
evenly spaced values per parameter, producing exactly
levels ** params
samples. Set the resolution explicitly with
--levels
(e.g.
--params 2 --levels 4
-> 16 samples). If you use
--budget
instead, the script back-computes
levels = round(budget ** (1/params))
and warns whenever the realized sample count differs from the requested budget (e.g.
--budget 20 --params 2
realizes 16 samples). For an exact design, pass a perfect power (
--budget 16
) or, preferably,
--levels
.

维度 <= 3 且需要全覆盖？
├── 是 → 使用析因法（factorial）
└── 否 → 目标是敏感性分析？
    ├── 是 → 使用准随机法（quasi-random，为首选；"sobol"为兼容写法但已弃用）
    └── 否 → 使用拉丁超立方抽样（lhs）

方法	适用场景	避免场景
`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
。

Choosing an Optimizer

选择优化器

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

Noise Level	Recommendation
Low	Gradient-based if derivatives available, else Bayesian Optimization
Medium	Bayesian Optimization with noise model
High	Evolutionary algorithms or robust Bayesian Optimization

维度 <= 10 且预算 <= 100？
├── 是 → 贝叶斯优化（Bayesian Optimization）
└── 否 → 维度 <= 20？
    ├── 是 → CMA-ES
    └── 否 → 带筛选的随机搜索

噪声水平	推荐方案
Low	若可获取导数则使用基于梯度的方法，否则使用贝叶斯优化
Medium	带噪声模型的贝叶斯优化
High	进化算法或鲁棒贝叶斯优化

Script Outputs (JSON Fields)

脚本输出（JSON字段）

Script	Output Fields
`scripts/doe_generator.py`	`samples` , `method` , `coverage` ( `count` , `dimension` ; plus `levels` and a top-level `requested_budget` / `note` for factorial)
`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`

脚本	输出字段
`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`

Workflow

工作流

Generate DOE with
```
scripts/doe_generator.py
```
Run simulations at DOE sample points (user's responsibility)
Summarize sensitivity with
```
scripts/sensitivity_summary.py
```
Choose optimizer using
```
scripts/optimizer_selector.py
```
(Optional) Fit surrogate with
```
scripts/surrogate_builder.py
```

使用
```
scripts/doe_generator.py
```
生成DOE抽样方案
在DOE抽样点运行模拟（由用户负责）
使用
```
scripts/sensitivity_summary.py
```
汇总敏感性分析结果
使用
```
scripts/optimizer_selector.py
```
选择优化器
（可选） 使用
```
scripts/surrogate_builder.py
```
拟合代理模型

CLI Examples

CLI示例

bash

undefined

bash

undefined

Generate 20 LHS samples for 3 parameters

为3个参数生成20个LHS样本

python3 scripts/doe_generator.py --params 3 --budget 20 --method lhs --json

Full factorial with 4 levels per parameter (2 params -> 16 samples)

每个参数取4个水平的全析因设计（2个参数 → 16个样本）

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

获取3维问题、50次评估预算下的优化器推荐

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

undefined

python3 scripts/surrogate_builder.py --x 0,1,2 --y 10,12,15 --model rbf --json

undefined

Conversational Workflow Example

对话式工作流示例

User: I need to calibrate thermal conductivity and diffusivity for my FEM simulation. I can run about 30 simulations.

Agent workflow:

Identify 2 parameters →
```
--params 2
```
Budget is 30 →
```
--budget 30
```

Use LHS for general exploration:

bash

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

After user runs simulations and provides outputs, summarize sensitivity:

bash

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

Recommend optimizer:

bash

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

用户：我需要为我的有限元模拟校准热导率和扩散率，我可以运行大约30次模拟。

Agent工作流：

识别出2个参数 →
```
--params 2
```
预算为30 →
```
--budget 30
```

使用LHS进行通用探索：

bash

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

用户运行模拟并提供输出后，汇总敏感性分析结果：

bash

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

推荐优化器：

bash

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

Error Handling

错误处理

Error	Cause	Resolution
`params must be positive`	Zero or negative dimension	Ask user for valid parameter count
`budget must be positive`	Zero or negative budget	Ask user for realistic simulation budget
`argument --method: invalid choice: <value> (choose from lhs, sobol, quasi-random, factorial)`	Invalid method (argparse)	Use decision guidance to pick a valid method
`could not convert string to float: <token>`	Non-numeric value in `--scores` / `--x` / `--y`	Reformat as `0.1,0.2,0.3`
`scores must be a comma-separated list`	Empty `--scores` input	Provide at least one numeric score

错误信息	原因	解决方法
`params must be positive`	参数维度为0或负数	请用户提供有效的参数数量
`budget must be positive`	预算为0或负数	请用户提供合理的模拟预算
`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` 输入为空	提供至少一个数值分数

Verification checklist

验证检查清单

Recorded the exact
```
doe_generator.py
```
```
coverage.count
```
and confirmed it matches the intended design — for
```
factorial
```
, verified
```
count == levels ** params
```
and that no
```
note
```
/
```
requested_budget
```
mismatch warning was emitted (or that the realized count is acceptable).
Confirmed the chosen
```
--method
```
matches the Decision Guidance for the actual dimension/goal, and that
```
quasi-random
```
was used instead of the deprecated
```
sobol
```
alias (no
```
DeprecationWarning
```
in output).
Recorded the
```
optimizer_selector.py
```
```
recommended
```
strategy and
```
expected_evals
```
, and verified
```
expected_evals <= budget
```
so the plan is feasible within the stated evaluation budget.
Logged the
```
sensitivity_summary.py
```
```
ranking
```
and checked whether the top sensitivity is
```
< 0.1
```
(the "All sensitivities are low" note); if so, did not over-interpret the ranking and revisited the output metric.
For surrogate fits, judged quality with
```
metrics.cv_error
```
(leave-one-out), NOT in-sample
```
mse
```
— especially for
```
rbf
```
, where
```
mse
```
is near zero by construction — and compared
```
cv_error
```
against
```
metrics.output_variance
```
to confirm the surrogate beats the constant-mean baseline.
Confirmed any reported
```
cv_error
```
is a finite number (not
```
NaN
```
), i.e. there were enough samples for leave-one-out (
```
poly
```
:
```
n > degree+1
```
;
```
rbf
```
:
```
n >= 3
```
).

记录
```
doe_generator.py
```
输出的
```
coverage.count
```
并确认其与预期设计匹配——对于析因法，需验证
```
count == levels ** params
```
且未触发
```
note
```
/预算不匹配警告（或确认实际样本数可接受）。
确认所选
```
--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
```
）。

Common pitfalls & rationalizations

常见误区及说明

Tempting shortcut	Why it's wrong / what to do
"RBF surrogate `mse` is ~0, so the model is excellent."	RBF is an exact interpolant — in-sample `mse` is near zero by construction and says nothing about generalization. Judge fit with `metrics.cv_error` and compare it to `output_variance` .
"I asked for `--budget 20` factorial, so I got 20 samples."	Factorial honors `levels ** params` , not the budget; `--budget 20 --params 2` realizes 16 samples and emits a `note` /warning. Use `--levels` for an exact, intended design.
" `sobol` gives me a true Sobol low-discrepancy sequence."	`sobol` is a deprecated alias that emits a `DeprecationWarning` and uses a simplified golden-ratio additive recurrence, not a true Sobol sequence. Use `quasi-random` ; for production Sobol use `scipy.stats.qmc` .
"The optimizer recommendation is just advice — budget doesn't matter."	The recommendation is gated on dimension AND budget (BO only for `dim<=10 AND budget<=100` ), and `expected_evals` is capped at the budget. Record both and confirm the plan fits the real budget.
"One sensitivity score is highest, so that parameter dominates."	The script only sorts the scores you pass in; it computes no sensitivity itself. If the top score is `< 0.1` it flags that all sensitivities are low — get the scores from a real screening/Sobol analysis before trusting the ranking.
"It printed JSON without erroring, so the result is valid."	Exit success only means inputs parsed. Verify the design size, `expected_evals <= budget` , a finite `cv_error` , and that the surrogate beats `output_variance` before trusting any output.

诱人的捷径	错误原因/正确做法
“RBF代理模型的 `mse` 约为0，所以模型非常优秀。”	RBF是精确插值器——样本内 `mse` 本质上接近零，无法说明泛化能力。需使用 `metrics.cv_error` 判断拟合质量，并与 `output_variance` 对比。
“我要求 `--budget 20` 的析因设计，所以得到了20个样本。”	析因设计遵循 `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` 时推荐贝叶斯优化），且 `expected_evals` 会被限制在预算范围内。需记录两者并确认方案符合实际预算。
“某个敏感性分数最高，所以该参数起主导作用。”	脚本仅对传入的分数进行排序；本身不计算敏感性。若最高分数 `< 0.1` ，会标记所有敏感性分数均较低——需通过真实的筛选/Sobol分析获取分数后再信任排序结果。
“输出了JSON且未报错，所以结果有效。”	执行成功仅表示输入解析正确。在信任任何输出前，需验证设计规模、 `expected_evals <= budget` 、有限的 `cv_error` ，以及代理模型优于 `output_variance` 。

Security

安全性

Input Validation

输入验证

```
sensitivity_summary.py
```
validates
```
--names
```
against
```
[a-zA-Z_][a-zA-Z0-9_ .-]*
```
with a 200-char limit, preventing shell metacharacter injection via crafted parameter names
All numeric list inputs are validated as finite numbers (
```
NaN
```
/
```
Inf
```
rejected)
Comma-separated value lists are capped (10,000 for scores, 100,000 for surrogate data) to prevent resource exhaustion
```
doe_generator.py
```
caps dimension at 1,000 and budget at 1,000,000;
```
optimizer_selector.py
```
caps dimension at 100,000 and budget at 10,000,000
```
--method
```
is validated against a fixed allowlist (
```
lhs
```
,
```
quasi-random
```
/
```
sobol
```
,
```
factorial
```
);
```
sobol
```
is an accepted but deprecated alias of
```
quasi-random
```
```
--noise
```
is validated against a fixed allowlist (
```
low
```
,
```
medium
```
,
```
high
```
)
```
--model
```
(surrogate type) is validated against a fixed allowlist (
```
rbf
```
,
```
poly
```
)
```
--levels
```
(factorial grid resolution) is validated as an integer in
```
[2, 1000]
```

```
sensitivity_summary.py
```
会校验
```
--names
```
是否符合
```
[a-zA-Z_][a-zA-Z0-9_ .-]*
```
格式且长度不超过200字符，防止通过构造参数名称注入shell元字符
所有数值列表输入均会被校验为有限数值（拒绝
```
NaN
```
/
```
Inf
```
）
逗号分隔的值列表会被限制数量（分数最多10000个，代理模型数据最多100000个），防止资源耗尽
```
doe_generator.py
```
限制维度最大为1000，预算最大为1000000；
```
optimizer_selector.py
```
限制维度最大为100000，预算最大为10000000
```
--method
```
会被校验为固定允许列表（
```
lhs
```
,
```
quasi-random
```
/
```
sobol
```
,
```
factorial
```
）；
```
sobol
```
是
```
quasi-random
```
的兼容但已弃用别名
```
--noise
```
会被校验为固定允许列表（
```
low
```
,
```
medium
```
,
```
high
```
）
```
--model
```
（代理模型类型）会被校验为固定允许列表（
```
rbf
```
,
```
poly
```
）
```
--levels
```
（析因网格分辨率）会被校验为
```
[2, 1000]
```
范围内的整数

File Access

文件访问

Scripts read no external files; all inputs are provided via CLI arguments
Scripts write only to stdout (JSON output); no files are created unless the agent explicitly uses the Write tool

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

Tool Restrictions

工具限制

Read: Used to inspect script source, references, and user data files
Write: Used to save DOE sample plans, sensitivity rankings, or optimizer recommendations; writes are scoped to the user's working directory
Grep/Glob: Used to locate relevant files and search references
The skill's
```
allowed-tools
```
excludes
```
Bash
```
to prevent the agent from executing arbitrary commands when processing user-provided parameter names and constraints

读取：用于检查脚本源码、参考资料和用户数据文件
写入：用于保存DOE抽样方案、敏感性排序或优化器推荐；写入范围限定在用户工作目录内
Grep/Glob：用于定位相关文件和搜索参考资料
本技能的
```
allowed-tools
```
排除了
```
Bash
```
，防止Agent处理用户提供的参数名称和约束时执行任意命令

Safety Measures

安全措施

No
```
eval()
```
,
```
exec()
```
, or dynamic code generation
All subprocess calls use explicit argument lists (no
```
shell=True
```
)
Reduced tool surface (no Bash) limits the agent to read/write operations only
Parameter names are sanitized before use, preventing injection via crafted identifiers

不使用
```
eval()
```
、
```
exec()
```
或动态代码生成
所有子进程调用均使用显式参数列表（不使用
```
shell=True
```
）
缩减工具范围（无Bash），将Agent限制为仅读写操作
参数名称会被清理后使用，防止通过构造标识符注入恶意内容

Limitations

局限性

Not for real-time optimization: Scripts provide recommendations, not live optimization loops
Surrogate is lightweight:
```
surrogate_builder.py
```
fits a real 1-D least-squares polynomial (
```
poly
```
) or Gaussian RBF interpolant (
```
rbf
```
) using only the standard library and reports honest residual
```
mse
```
, leave-one-out
```
cv_error
```
, and the data
```
output_variance
```
; for production use scipy/scikit-learn/GPyTorch. For
```
rbf
```
, in-sample
```
mse
```
is near zero by construction (exact interpolation) — judge fit quality with
```
cv_error
```
No automatic simulation execution: User must run simulations externally and provide results

不支持实时优化：脚本仅提供推荐，不支持实时优化循环
代理模型轻量化：
```
surrogate_builder.py
```
仅使用标准库拟合一维最小二乘多项式（
```
poly
```
）或高斯RBF插值器（
```
rbf
```
），并如实报告残差
```
mse
```
、留一法
```
cv_error
```
和数据
```
output_variance
```
；生产环境请使用scipy/scikit-learn/GPyTorch。对于
```
rbf
```
模型，样本内
```
mse
```
本质上接近零（精确插值）——需使用
```
cv_error
```
判断拟合质量
不自动执行模拟：用户需在外部运行模拟并提供结果

References

参考资料

```
references/doe_methods.md
```
- Detailed DOE method comparison
```
references/optimizer_selection.md
```
- Optimizer algorithm details
```
references/sensitivity_guidelines.md
```
- Sensitivity analysis interpretation
```
references/surrogate_guidelines.md
```
- Surrogate model selection

```
references/doe_methods.md
```
- DOE方法详细对比
```
references/optimizer_selection.md
```
- 优化器算法细节
```
references/sensitivity_guidelines.md
```
- 敏感性分析解读指南
```
references/surrogate_guidelines.md
```
- 代理模型选择指南

Version History

版本历史

v1.2.2 (2026-06-24): Added Verification checklist and Common pitfalls & rationalizations sections to drive evidence-based use of the DOE, optimizer, sensitivity, and surrogate scripts
v1.2.0 (2026-06-23): Real surrogate fits (
```
poly
```
least-squares,
```
rbf
```
interpolation) with honest
```
mse
```
/
```
cv_error
```
/
```
output_variance
```
; explicit factorial
```
--levels
```
with budget-mismatch warnings; BO dimension cutoff harmonized to dim<=10; corrected Security/Error-Handling/output-field docs to match script behavior
v1.1.0 (2024-12-24): Enhanced documentation, decision guidance, conversational examples
v1.0.0: Initial release with core scripts

v1.2.2（2026-06-24）：新增验证检查清单和常见误区及说明章节，指导基于证据使用DOE、优化器、敏感性分析和代理模型脚本
v1.2.0（2026-06-23）：实现真实代理模型拟合（
```
poly
```
最小二乘、
```
rbf
```
插值），提供真实的
```
mse
```
/
```
cv_error
```
/
```
output_variance
```
；析因法新增显式
```
--levels
```
参数及预算不匹配警告；贝叶斯优化的维度限制统一为dim<=10；修正安全性/错误处理/输出字段文档以匹配脚本行为
v1.1.0（2024-12-24）：增强文档、决策指南和对话示例
v1.0.0：初始版本，包含核心脚本