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)
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 |
Decision Guidance
Choosing a DOE Method
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 |
sobol |
Sensitivity analysis, uniform coverage |
Very high dimensions (>20) |
factorial |
Low dimension (<4), need all corners |
High dimension (exponential growth) |
Choosing an Optimizer
Is dimension <= 5 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 |
Script Outputs (JSON Fields)
| Script |
Output Fields |
scripts/doe_generator.py |
samples, method, coverage |
scripts/optimizer_selector.py |
recommended, expected_evals, notes |
scripts/sensitivity_summary.py |
ranking, notes |
scripts/surrogate_builder.py |
model_type, metrics, 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
CLI Examples
# Generate 20 LHS samples for 3 parameters
python3 scripts/doe_generator.py --params 3 --budget 20 --method lhs --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
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:
python3 scripts/doe_generator.py --params 2 --budget 30 --method lhs --json
- After user runs simulations and provides outputs, summarize sensitivity:
python3 scripts/sensitivity_summary.py --scores 0.7,0.3 --names conductivity,diffusivity --json
- Recommend optimizer:
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 |
method must be lhs, sobol, or factorial |
Invalid method |
Use decision guidance to pick valid method |
scores must be comma-separated |
Malformed input |
Reformat as 0.1,0.2,0.3 |
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, sobol, factorial)
--noise is validated against a fixed allowlist (low, medium, high)
--model (surrogate type) is validated against a fixed allowlist (rbf, linear, polynomial)
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
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
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
Limitations
- Not for real-time optimization: Scripts provide recommendations, not live optimization loops
- Surrogate is a placeholder:
surrogate_builder.py computes basic metrics; replace with actual model for production
- No automatic simulation execution: User must run simulations externally and provide results
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
Version History
- v1.1.0 (2024-12-24): Enhanced documentation, decision guidance, conversational examples
- v1.0.0: Initial release with core scripts
1---2name: parameter-optimization3description: >4 Explore and optimize simulation parameters via design of experiments (DOE),5 sensitivity analysis, and optimizer selection — generate Latin Hypercube,6 quasi-random, or factorial sample plans, rank parameter influence with7 sensitivity scores, recommend Bayesian optimization, CMA-ES, or gradient-8 based methods based on dimension and budget, and fit surrogate models for9 expensive evaluations. Use when calibrating material properties against10 experimental data, planning a parameter sweep, performing uncertainty11 quantification, or choosing an optimization strategy for a simulation12 with a limited evaluation budget, even if the user only says "which13 parameters matter most" or "how do I calibrate my model."14allowed-tools: Read, Write, Grep, Glob15metadata:16 source: https://skillmd.com/skills/zuoguyoupan2023/parameter-optimization17 author: HeshamFS18 version: "1.1.0"19 security_tier: medium20 security_reviewed: true21 tested_with:22 - claude-code23 - gemini-cli24 - vs-code-copilot25 eval_cases: 526 last_reviewed: "2026-03-26"27---2829# Parameter Optimization3031## Goal3233Provide a workflow to design experiments, rank parameter influence, and select optimization strategies for materials simulation calibration.3435## Requirements3637- Python 3.10+38- No external dependencies (uses Python standard library only)3940## Inputs to Gather4142Before running any scripts, collect from the user:4344| Input | Description | Example |45|-------|-------------|---------|46| Parameter bounds | Min/max for each parameter with units | `kappa: [0.1, 10.0] W/mK` |47| Evaluation budget | Max number of simulations allowed | `50 runs` |48| Noise level | Stochasticity of simulation outputs | `low`, `medium`, `high` |49| Constraints | Feasibility rules or forbidden regions | `kappa + mobility < 5` |5051## Decision Guidance5253### Choosing a DOE Method5455```56Is dimension <= 3 AND full coverage needed?57├── YES → Use factorial58└── NO → Is sensitivity analysis the goal?59 ├── YES → Use quasi-random (preferred; "sobol" is accepted but deprecated)60 └── NO → Use lhs (Latin Hypercube)61```6263| Method | Best For | Avoid When |64|--------|----------|------------|65| `lhs` | General exploration, moderate dimensions (3-20) | Need exact grid coverage |66| `sobol` | Sensitivity analysis, uniform coverage | Very high dimensions (>20) |67| `factorial` | Low dimension (<4), need all corners | High dimension (exponential growth) |6869### Choosing an Optimizer7071```72Is dimension <= 5 AND budget <= 100?73├── YES → Bayesian Optimization74└── NO → Is dimension <= 20?75 ├── YES → CMA-ES76 └── NO → Random Search with screening77```7879| Noise Level | Recommendation |80|-------------|----------------|81| Low | Gradient-based if derivatives available, else Bayesian Optimization |82| Medium | Bayesian Optimization with noise model |83| High | Evolutionary algorithms or robust Bayesian Optimization |8485## Script Outputs (JSON Fields)8687| Script | Output Fields |88|--------|---------------|89| `scripts/doe_generator.py` | `samples`, `method`, `coverage` |90| `scripts/optimizer_selector.py` | `recommended`, `expected_evals`, `notes` |91| `scripts/sensitivity_summary.py` | `ranking`, `notes` |92| `scripts/surrogate_builder.py` | `model_type`, `metrics`, `notes` |9394## Workflow95961. **Generate DOE** with `scripts/doe_generator.py`972. **Run simulations** at DOE sample points (user's responsibility)983. **Summarize sensitivity** with `scripts/sensitivity_summary.py`994. **Choose optimizer** using `scripts/optimizer_selector.py`1005. **(Optional)** Fit surrogate with `scripts/surrogate_builder.py`101102## CLI Examples103104```bash105# Generate 20 LHS samples for 3 parameters106python3 scripts/doe_generator.py --params 3 --budget 20 --method lhs --json107108# Rank parameters by sensitivity scores109python3 scripts/sensitivity_summary.py --scores 0.2,0.5,0.3 --names kappa,mobility,W --json110111# Get optimizer recommendation for 3D problem with 50 eval budget112python3 scripts/optimizer_selector.py --dim 3 --budget 50 --noise low --json113114# Build surrogate model from simulation data115python3 scripts/surrogate_builder.py --x 0,1,2 --y 10,12,15 --model rbf --json116```117118## Conversational Workflow Example119120**User**: I need to calibrate thermal conductivity and diffusivity for my FEM simulation. I can run about 30 simulations.121122**Agent workflow**:1231. Identify 2 parameters → `--params 2`1242. Budget is 30 → `--budget 30`1253. Use LHS for general exploration:126 ```bash127 python3 scripts/doe_generator.py --params 2 --budget 30 --method lhs --json128 ```1294. After user runs simulations and provides outputs, summarize sensitivity:130 ```bash131 python3 scripts/sensitivity_summary.py --scores 0.7,0.3 --names conductivity,diffusivity --json132 ```1335. Recommend optimizer:134 ```bash135 python3 scripts/optimizer_selector.py --dim 2 --budget 30 --noise low --json136 ```137138## Error Handling139140| Error | Cause | Resolution |141|-------|-------|------------|142| `params must be positive` | Zero or negative dimension | Ask user for valid parameter count |143| `budget must be positive` | Zero or negative budget | Ask user for realistic simulation budget |144| `method must be lhs, sobol, or factorial` | Invalid method | Use decision guidance to pick valid method |145| `scores must be comma-separated` | Malformed input | Reformat as `0.1,0.2,0.3` |146147## Security148149### Input Validation150- `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 names151- All numeric list inputs are validated as finite numbers (`NaN`/`Inf` rejected)152- Comma-separated value lists are capped (10,000 for scores, 100,000 for surrogate data) to prevent resource exhaustion153- `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,000154- `--method` is validated against a fixed allowlist (`lhs`, `sobol`, `factorial`)155- `--noise` is validated against a fixed allowlist (`low`, `medium`, `high`)156- `--model` (surrogate type) is validated against a fixed allowlist (`rbf`, `linear`, `polynomial`)157158### File Access159- Scripts read no external files; all inputs are provided via CLI arguments160- Scripts write only to stdout (JSON output); no files are created unless the agent explicitly uses the Write tool161162### Tool Restrictions163- **Read**: Used to inspect script source, references, and user data files164- **Write**: Used to save DOE sample plans, sensitivity rankings, or optimizer recommendations; writes are scoped to the user's working directory165- **Grep/Glob**: Used to locate relevant files and search references166- The skill's `allowed-tools` excludes `Bash` to prevent the agent from executing arbitrary commands when processing user-provided parameter names and constraints167168### Safety Measures169- No `eval()`, `exec()`, or dynamic code generation170- All subprocess calls use explicit argument lists (no `shell=True`)171- Reduced tool surface (no Bash) limits the agent to read/write operations only172- Parameter names are sanitized before use, preventing injection via crafted identifiers173174## Limitations175176- **Not for real-time optimization**: Scripts provide recommendations, not live optimization loops177- **Surrogate is a placeholder**: `surrogate_builder.py` computes basic metrics; replace with actual model for production178- **No automatic simulation execution**: User must run simulations externally and provide results179180## References181182- `references/doe_methods.md` - Detailed DOE method comparison183- `references/optimizer_selection.md` - Optimizer algorithm details184- `references/sensitivity_guidelines.md` - Sensitivity analysis interpretation185- `references/surrogate_guidelines.md` - Surrogate model selection186187## Version History188189- **v1.1.0** (2024-12-24): Enhanced documentation, decision guidance, conversational examples190- **v1.0.0**: Initial release with core scripts