simulation-orchestrator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Simulation Orchestrator

模拟编排工具

Goal

目标

Provide tools to manage multi-simulation campaigns: generate parameter sweeps, track job execution status, and aggregate results from completed runs.

提供工具管理多模拟任务：生成参数扫描配置、跟踪任务执行状态、汇总已完成运行的结果。

Requirements

要求

Python 3.10+
No external dependencies (uses Python standard library only)
Works on Linux, macOS, and Windows

Python 3.10+
无外部依赖（仅使用Python标准库）
支持Linux、macOS和Windows系统

Inputs to Gather

需要收集的输入信息

Before running orchestration scripts, collect from the user:

Input	Description	Example
Base config	Template simulation configuration	`base_config.json`
Parameter ranges	Parameters to sweep with bounds	`dt:[1e-4,1e-2],kappa:[0.1,1.0]`
Sweep method	How to sample parameter space	`grid` , `lhs` , `linspace`
Output directory	Where to store campaign files	`./campaign_001`
Simulation command	Command to run each simulation	`python sim.py --config {config}`

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

输入项	描述	示例
基础配置	模拟配置模板	`base_config.json`
参数范围	待扫描参数的取值区间	`dt:[1e-4,1e-2],kappa:[0.1,1.0]`
扫描方法	参数空间的采样方式	`grid` , `lhs` , `linspace`
输出目录	任务文件的存储路径	`./campaign_001`
模拟命令	运行单个模拟的命令	`python sim.py --config {config}`

Decision Guidance

决策指引

Choosing a Sweep Method

选择扫描方法

Need every combination (full factorial)?
├── YES → Use grid (warning: exponential growth with parameters)
└── NO → Is space-filling coverage needed?
    ├── YES → Use lhs (Latin Hypercube Sampling)
    └── NO → Use linspace for uniform sampling per parameter

Method	Best For	Sample Count
`grid`	Low dimensions (1-3), need exact corners	n^d (exponential)
`linspace`	1D sweeps, uniform spacing	n per parameter
`lhs`	High dimensions, space-filling	user-specified budget

需要所有参数组合（全因子）？
├── 是 → 使用grid（注意：参数数量增加时组合数呈指数增长）
└── 否 → 是否需要空间填充式覆盖？
    ├── 是 → 使用lhs（Latin Hypercube Sampling）
    └── 否 → 使用linspace进行单参数均匀采样

方法	适用场景	样本数量
`grid`	低维度（1-3个参数），需要精确覆盖所有边界	n^d（指数级增长）
`linspace`	一维扫描，均匀间隔采样	每个参数取n个值
`lhs`	高维度，需要空间填充式覆盖	用户指定的采样数量

Campaign Size Guidelines

任务规模指南

Parameters	Grid Points Each	Total Runs	Recommendation
1	10	10	Grid is fine
2	10	100	Grid acceptable
3	10	1,000	Consider LHS
4+	10	10,000+	Use LHS or DOE

参数数量	每个参数的网格点数	总运行次数	建议
1	10	10	使用grid即可
2	10	100	使用grid可行
3	10	1,000	考虑使用LHS
4+	10	10,000+	使用LHS或DOE

Script Outputs (JSON Fields)

脚本输出（JSON字段）

Script	Output Fields
`scripts/sweep_generator.py`	`configs` , `parameter_space` , `sweep_method` , `total_runs`
`scripts/campaign_manager.py --action init`	`campaign_id` , `total_jobs` , `config_dir` , `command_template`
`scripts/campaign_manager.py --action status`	`campaign_id` , `status` , `jobs` , `progress` , `total_jobs` , `created_at`
`scripts/campaign_manager.py --action list`	`jobs` (array of job records)
`scripts/job_tracker.py`	`job_id` , `status` , `start_time` , `end_time` , `exit_code`
`scripts/result_aggregator.py`	`summary` (incl. `minimize` ), `statistics` , `best_run` , `failed_runs`

Note on swept parameter names:
sweep_generator.py
writes each swept value into the base config by key path. A bare name (e.g.
kappa
) overwrites a top-level key; a dot-notation name (e.g.
parameters.kappa
) targets a nested key. The swept key path must match where the solver reads the value — sweeping
kappa
against a config that nests
parameters.kappa
would add an unused top-level key and silently leave the base value in place. See
references/sweep_strategies.md
.

脚本	输出字段
`scripts/sweep_generator.py`	`configs` , `parameter_space` , `sweep_method` , `total_runs`
`scripts/campaign_manager.py --action init`	`campaign_id` , `total_jobs` , `config_dir` , `command_template`
`scripts/campaign_manager.py --action status`	`campaign_id` , `status` , `jobs` , `progress` , `total_jobs` , `created_at`
`scripts/campaign_manager.py --action list`	`jobs` （任务记录数组）
`scripts/job_tracker.py`	`job_id` , `status` , `start_time` , `end_time` , `exit_code`
`scripts/result_aggregator.py`	`summary` （包含 `minimize` ）, `statistics` , `best_run` , `failed_runs`

关于扫描参数名称的说明：
sweep_generator.py
会按键路径将每个扫描值写入基础配置。裸名称（如
kappa
）会覆盖顶层键；点符号名称（如
parameters.kappa
）会定位嵌套键。扫描的键路径必须与求解器读取值的位置匹配——如果针对嵌套了
parameters.kappa
的配置扫描
kappa
，会添加一个未使用的顶层键，而基础值会保持不变且无提示。详见
references/sweep_strategies.md
。

Workflow

工作流

Step 1: Generate Parameter Sweep

步骤1：生成参数扫描配置

Create configurations for all parameter combinations:

bash

python3 scripts/sweep_generator.py \
    --base-config base_config.json \
    --params "dt:1e-4:1e-2:5,kappa:0.1:1.0:3" \
    --method linspace \
    --output-dir ./campaign_001 \
    --json

创建所有参数组合的配置文件：

bash

python3 scripts/sweep_generator.py \
    --base-config base_config.json \
    --params "dt:1e-4:1e-2:5,kappa:0.1:1.0:3" \
    --method linspace \
    --output-dir ./campaign_001 \
    --json

Step 2: Initialize Campaign

步骤2：初始化任务

Create campaign tracking structure:

bash

python3 scripts/campaign_manager.py \
    --action init \
    --config-dir ./campaign_001 \
    --command "python sim.py --config {config}" \
    --json

创建任务跟踪结构：

bash

python3 scripts/campaign_manager.py \
    --action init \
    --config-dir ./campaign_001 \
    --command "python sim.py --config {config}" \
    --json

Step 3: Track Job Status

步骤3：跟踪任务状态

Monitor running jobs:

bash

python3 scripts/job_tracker.py \
    --campaign-dir ./campaign_001 \
    --update \
    --json

监控运行中的任务：

bash

python3 scripts/job_tracker.py \
    --campaign-dir ./campaign_001 \
    --update \
    --json

Step 4: Aggregate Results

步骤4：汇总结果

Combine results from completed runs:

bash

python3 scripts/result_aggregator.py \
    --campaign-dir ./campaign_001 \
    --metric final_energy \
    --json

result_aggregator.py

minimizes by default:

best_run

is the run with the lowest metric value (and

summary.minimize

true

). If higher is better (e.g. yield, accuracy, throughput), pass

--maximize

best_run

becomes the highest value:

bash

undefined

合并已完成运行的结果：

bash

python3 scripts/result_aggregator.py \
    --campaign-dir ./campaign_001 \
    --metric final_energy \
    --json

result_aggregator.py

默认执行最小化操作：

best_run

是指标值最低的运行（

summary.minimize

为

true

）。如果指标值越高越好（如产量、准确率、吞吐量），需传入

--maximize

参数，此时

best_run

会对应指标值最高的运行：

bash

undefined

Higher is better -> select the maximum

指标值越高越好 → 选择最大值

python3 scripts/result_aggregator.py
--campaign-dir ./campaign_001
--metric yield
--maximize
--json


> **Decision guidance**: If higher is better (yield, accuracy, throughput), pass
> `--maximize`; otherwise the reported `best_run` is the **minimum**.

python3 scripts/result_aggregator.py
--campaign-dir ./campaign_001
--metric yield
--maximize
--json


> **决策指引**：如果指标值越高越好（产量、准确率、吞吐量），传入`--maximize`；否则默认`best_run`对应指标值的最小值。

CLI Examples

CLI示例

bash

undefined

bash

undefined

Generate 5x3=15 runs varying dt (5 values) and kappa (3 values)

生成5×3=15次运行，dt取5个值，kappa取3个值

python3 scripts/sweep_generator.py
--base-config sim.json
--params "dt:1e-4:1e-2:5,kappa:0.1:1.0:3"
--method linspace
--output-dir ./sweep_001
--json

Generate LHS samples for 4 parameters with budget of 20 runs

为4个参数生成LHS样本，采样数量为20

python3 scripts/sweep_generator.py
--base-config sim.json
--params "dt:1e-4:1e-2,kappa:0.1:1.0,M:1e-6:1e-4,W:0.5:2.0"
--method lhs
--samples 20
--output-dir ./lhs_001
--json

Check campaign status

查看任务状态

python3 scripts/campaign_manager.py
--action status
--config-dir ./sweep_001
--json

List jobs (read-only), optionally filtered by status

列出任务（只读），可按状态筛选

python3 scripts/campaign_manager.py
--action list
--config-dir ./sweep_001
--status-filter failed
--json

Get summary statistics from completed runs (minimize: best = lowest)

汇总已完成运行的统计信息（最小化：最优为最低值）

python3 scripts/result_aggregator.py
--campaign-dir ./sweep_001
--metric final_energy
--json

Maximization metric: best = highest value (yield, accuracy, throughput)

最大化指标：最优为最高值（产量、准确率、吞吐量）

python3 scripts/result_aggregator.py
--campaign-dir ./sweep_001
--metric yield
--maximize
--json

undefined

python3 scripts/result_aggregator.py
--campaign-dir ./sweep_001
--metric yield
--maximize
--json

undefined

Conversational Workflow Example

对话式工作流示例

User: I want to run a parameter sweep on dt and kappa for my phase-field simulation. I want to try 5 values of dt between 1e-4 and 1e-2, and 4 values of kappa between 0.1 and 1.0.

Agent workflow:

Calculate total runs: 5 x 4 = 20 runs

Generate sweep configurations:

bash

python3 scripts/sweep_generator.py \
    --base-config simulation.json \
    --params "dt:1e-4:1e-2:5,kappa:0.1:1.0:4" \
    --method linspace \
    --output-dir ./dt_kappa_sweep \
    --json

Initialize campaign:

bash

python3 scripts/campaign_manager.py \
    --action init \
    --config-dir ./dt_kappa_sweep \
    --command "python phase_field.py --config {config}" \
    --json

After user runs simulations, aggregate results:

bash

python3 scripts/result_aggregator.py \
    --campaign-dir ./dt_kappa_sweep \
    --metric interface_width \
    --json

用户：我想为我的相场模拟开展dt和kappa的参数扫描。dt要在1e-4到1e-2之间取5个值，kappa要在0.1到1.0之间取4个值。

Agent工作流:

计算总运行次数：5×4=20次

生成扫描配置：

bash

python3 scripts/sweep_generator.py \
    --base-config simulation.json \
    --params "dt:1e-4:1e-2:5,kappa:0.1:1.0:4" \
    --method linspace \
    --output-dir ./dt_kappa_sweep \
    --json

初始化任务：

bash

python3 scripts/campaign_manager.py \
    --action init \
    --config-dir ./dt_kappa_sweep \
    --command "python phase_field.py --config {config}" \
    --json

用户运行模拟后，汇总结果：

bash

python3 scripts/result_aggregator.py \
    --campaign-dir ./dt_kappa_sweep \
    --metric interface_width \
    --json

Error Handling

错误处理

Error	Cause	Resolution
`Base config not found`	Invalid file path	Verify base config file exists
`Invalid parameter format`	Malformed param string	Use format `name:min:max:count` or `name:min:max`
`Output directory exists`	Would overwrite	Use `--force` or choose new directory
`No completed jobs`	No results to aggregate	Wait for jobs to complete or check for failures
`Metric not found`	Result files missing field	Verify metric name in result JSON

错误	原因	解决方法
`Base config not found`	文件路径无效	确认基础配置文件存在
`Invalid parameter format`	参数格式错误	使用 `name:min:max:count` 或 `name:min:max` 格式
`Output directory exists`	会覆盖已有内容	使用 `--force` 参数或选择新目录
`No completed jobs`	无结果可汇总	等待任务完成或检查失败原因
`Metric not found`	结果文件缺少指定字段	确认结果JSON中的指标名称正确

Integration with Other Skills

与其他技能的集成

The simulation-orchestrator works with other simulation-workflow skills:

parameter-optimization          simulation-orchestrator
        │                              │
        │ DOE samples ────────────────>│ Generate configs
        │                              │
        │                              │ Run simulations
        │                              │
        │<──────────────────────────── │ Aggregate results
        │                              │
        │ Sensitivity analysis         │
        │ Optimizer selection          │

模拟编排工具可与其他模拟工作流技能配合使用：

parameter-optimization          simulation-orchestrator
        │                              │
        │ DOE样本 ────────────────>│ 生成配置
        │                              │
        │                              │ 运行模拟
        │                              │
        │<──────────────────────────── │ 汇总结果
        │                              │
        │ 敏感性分析                  │
        │ 优化器选择                  │

Typical Combined Workflow

典型组合工作流

Use
```
parameter-optimization/doe_generator.py
```
to get sample points

Use

simulation-orchestrator/sweep_generator.py

to create configs

Run simulations (user's responsibility)

Use

simulation-orchestrator/result_aggregator.py

to collect results

Use

parameter-optimization/sensitivity_summary.py

to analyze

使用
```
parameter-optimization/doe_generator.py
```
获取样本点

使用

simulation-orchestrator/sweep_generator.py

创建配置

运行模拟（用户负责）

使用

simulation-orchestrator/result_aggregator.py

收集结果

使用

parameter-optimization/sensitivity_summary.py

进行分析

Verification checklist

验证清单

Before trusting a campaign's

best_run

or summary statistics, record concrete evidence for each item:

Confirmed the swept key path actually changed the value the solver reads: opened at least one generated
```
config_NNNN.json
```
and verified the swept parameter (e.g.
```
parameters.kappa
```
) holds the expected value at the expected nesting level, not a duplicate unused top-level key (
```
sweep_generator.py
```
writes by key path).
Reconciled job accounting from
```
result_aggregator.py --json
```
: recorded
```
summary.total_jobs
```
,
```
summary.completed
```
, and
```
summary.failed
```
, and confirmed
```
completed + failed == total_jobs
```
. Any shortfall means runs were silently skipped (missing result file or
```
extract_metric
```
returned
```
None
```
) and must be investigated, not ignored.
Confirmed
```
completed > 0
```
and that the recorded
```
summary.metric
```
matches the field the solver actually writes. A typo'd or absent metric makes
```
extract_metric
```
return
```
None
```
, yielding zero completed runs with no error.
Recorded
```
summary.minimize
```
and confirmed it matches the intended direction (default minimize;
```
--maximize
```
for yield/accuracy/throughput) before quoting
```
best_run
```
.
Did NOT treat
```
job_tracker.py
```
"completed" as physical success: it flags a job completed purely from a result-file's existence and stamps
```
exit_code
```
0 — independently checked the run's real exit status / solver logs for non-zero codes or NaN/Inf output.
Applied an outlier/sanity check to the metric values (e.g. Tukey 1.5x IQR from
```
references/aggregation_methods.md
```
) and confirmed
```
best_run.value
```
is physically plausible, not a crashed run that emitted a spurious extremum.
For LHS sweeps, recorded the
```
--seed
```
used and saved
```
manifest.json
```
(parameter bounds,
```
total_runs
```
,
```
parameter_space
```
) so the sample set is reproducible.

在信任任务的

best_run

或统计摘要前，需逐一确认以下事项：

确认扫描的键路径确实修改了求解器读取的值：打开至少一个生成的
```
config_NNNN.json
```
，验证扫描参数（如
```
parameters.kappa
```
）在预期的嵌套层级上有预期值，而非出现一个未使用的重复顶层键（
```
sweep_generator.py
```
按键路径写入）。
核对
```
result_aggregator.py --json
```
的任务统计：记录
```
summary.total_jobs
```
、
```
summary.completed
```
和
```
summary.failed
```
，确认
```
completed + failed == total_jobs
```
。若不相等，说明有运行被静默跳过（缺少结果文件或
```
extract_metric
```
返回
```
None
```
），必须排查原因，不可忽略。
确认
```
completed > 0
```
，且记录的
```
summary.metric
```
与求解器实际输出的字段一致。若指标名称拼写错误或不存在，
```
extract_metric
```
会返回
```
None
```
，导致
```
completed
```
为0且无错误提示。
记录
```
summary.minimize
```
并确认其与预期的优化方向一致（默认最小化；针对产量/准确率/吞吐量使用
```
--maximize
```
），再引用
```
best_run
```
。
不要将
```
job_tracker.py
```
的“completed”视为实际运行成功：它仅根据结果文件的存在标记“completed”并硬编码
```
exit_code
```
为0——需独立检查运行的实际退出状态/求解器日志，确认是否有非零代码或NaN/Inf输出。
对指标值进行异常值/合理性检查（如参考
```
references/aggregation_methods.md
```
中的Tukey 1.5x IQR方法），确认
```
best_run.value
```
符合物理逻辑，而非崩溃运行产生的虚假极值。
对于LHS扫描，记录使用的
```
--seed
```
并保存
```
manifest.json
```
（参数范围、
```
total_runs
```
、
```
parameter_space
```
），确保样本集可复现。

Common pitfalls & rationalizations

常见误区与合理化借口

Tempting shortcut	Why it's wrong / what to do
"The job tracker says completed, so the run succeeded."	`job_tracker.py` marks "completed" whenever a result file exists and hard-codes `exit_code` 0 — it never reads the actual exit code. A crashed run that wrote a partial result file looks identical to a clean one. Check the solver's real exit status and output validity.
" `completed` is high, so I have all my results."	Jobs with a missing result file or a metric that `extract_metric` can't read are silently skipped — neither counted as `completed` nor `failed` . Reconcile `completed + failed` against `total_jobs` ; a gap means lost runs.
"Aggregation returned a `best_run` , so that's the optimum."	By default the aggregator minimizes. If higher is better you must pass `--maximize` , or `best_run` is the worst point. Always record `summary.minimize` and confirm the direction.
"I swept `kappa` , so the runs vary."	`sweep_generator.py` writes by key path. If the base config nests the value under `parameters.kappa` but you sweep the bare name `kappa` , every config keeps the original nested value and gains an unused top-level key — the sweep is scientifically meaningless. Sweep the exact dotted path the solver reads.
"The metric name is close enough."	A misspelled or absent metric makes `extract_metric` return `None` for every run, so `completed` is 0 and statistics are empty — with no error raised. Verify the metric matches the solver's output field exactly.
"Grid covers everything, so use it for all my parameters."	Grid is `n^d` — it explodes exponentially (4 params x 10 = 10,000 runs). For 4+ dimensions use `lhs` with a deliberate budget; reserve grid for 1-3 parameters.
"LHS is random, so I don't need to record anything."	LHS is reproducible only with a fixed `--seed` . Without recording the seed (and `manifest.json` ), the sample set cannot be regenerated or defended.

诱人的捷径	错误原因及正确做法
“任务跟踪器显示已完成，所以运行成功了。”	`job_tracker.py` 仅在结果文件存在时标记“completed”并硬编码 `exit_code` 为0——它从不读取实际的退出代码。崩溃后生成部分结果文件的运行，看起来与正常运行完全一致。需检查求解器的实际退出状态和输出有效性。
“已完成的任务数量很多，所以我已经拿到所有结果了。”	缺少结果文件或 `extract_metric` 无法读取指标的任务会被静默跳过——既不会被计入 `completed` 也不会被计入 `failed` 。核对 `completed + failed` 与 `total_jobs` 的数值；若有差距，说明有运行丢失。
“汇总结果返回了 `best_run` ，那就是最优解。”	汇总器默认执行最小化操作。如果指标值越高越好，必须传入 `--maximize` ，否则 `best_run` 会对应最差的点。务必记录 `summary.minimize` 并确认优化方向。
“我扫描了 `kappa` ，所以所有运行的参数都不同。”	`sweep_generator.py` 按键路径写入值。如果基础配置中 `kappa` 嵌套在 `parameters.kappa` 下，但你扫描的是裸名称 `kappa` ，所有配置都会保留原始的嵌套值，并新增一个未使用的顶层键——这样的扫描在科学上毫无意义。需扫描求解器实际读取的完整点符号路径。
“指标名称差不多就行。”	拼写错误或不存在的指标会导致 `extract_metric` 对所有运行返回 `None` ，因此 `completed` 为0且统计结果为空——不会有任何错误提示。需确认指标名称与求解器输出字段完全一致。
“网格能覆盖所有情况，所以所有参数都用网格扫描。”	网格扫描的数量是 `n^d` ——呈指数级增长（4个参数×10个值=10000次运行）。对于4个及以上参数，使用 `lhs` 并指定合理的采样数量；网格扫描仅适用于1-3个参数。
“LHS是随机的，所以不需要记录任何信息。”	只有在固定 `--seed` 的情况下，LHS样本才是可复现的。如果不记录种子（和 `manifest.json` ），样本集无法重新生成或验证。

Security

安全性

Input Validation

输入验证

Metric names (
```
result_aggregator.py --metric
```
) are validated against
```
[a-zA-Z_][a-zA-Z0-9_.]*
```
to prevent traversal or injection via crafted keys
Swept parameter names (
```
sweep_generator.py --params
```
) are validated against
```
[a-zA-Z_][a-zA-Z0-9_]*(.[a-zA-Z_][a-zA-Z0-9_]*)*
```
(dot notation for nested keys); invalid names are rejected
```
campaign_manager.py
```
validates command templates to reject shell chaining operators (
```
;
```
,
```
|
```
,
```
&
```
, backticks,
```
$
```
)
```
--params
```
format strings are parsed and validated (
```
name:min:max:count
```
with finite numeric bounds —
```
NaN
```
/
```
Inf
```
rejected —
```
min < max
```
, and positive integer counts capped at 100,000); at most 32 parameters per sweep
```
--method
```
is validated against a fixed allowlist (
```
grid
```
,
```
linspace
```
,
```
lhs
```
)
```
--samples
```
is validated as a positive integer with an upper bound (max 1,000,000)
```
--action
```
is validated against a fixed allowlist (
```
init
```
,
```
status
```
,
```
list
```
); for the read-only
```
list
```
action,
```
--status-filter
```
is validated against
```
pending
```
,
```
running
```
,
```
completed
```
,
```
failed
```

指标名称（
```
result_aggregator.py --metric
```
）会验证是否符合
```
[a-zA-Z_][a-zA-Z0-9_.]*
```
格式，防止通过构造的键进行路径遍历或注入攻击
扫描参数名称（
```
sweep_generator.py --params
```
）会验证是否符合
```
[a-zA-Z_][a-zA-Z0-9_]*(.[a-zA-Z_][a-zA-Z0-9_]*)*
```
格式（嵌套键使用点符号）；无效名称会被拒绝
```
campaign_manager.py
```
会验证命令模板，拒绝shell链式操作符（
```
;
```
、
```
|
```
、
```
&
```
、反引号、
```
$
```
）
```
--params
```
格式字符串会被解析和验证（格式为
```
name:min:max:count
```
，数值区间有限——拒绝
```
NaN
```
/
```
Inf
```
——
```
min < max
```
，正整数数量上限为100000）；每次扫描最多支持32个参数
```
--method
```
会验证是否在固定允许列表中（
```
grid
```
、
```
linspace
```
、
```
lhs
```
）
```
--samples
```
会验证为正整数且有上限（最大1000000）
```
--action
```
会验证是否在固定允许列表中（
```
init
```
、
```
status
```
、
```
list
```
）；对于只读的
```
list
```
操作，
```
--status-filter
```
会验证是否为
```
pending
```
、
```
running
```
、
```
completed
```
、
```
failed
```

File Access

文件访问

```
sweep_generator.py
```
reads a single base config file (JSON) specified by
```
--base-config
```
and writes generated configs to
```
--output-dir
```
```
result_aggregator.py
```
enforces a 10 MB file-size limit per result file, maximum JSON nesting depth, and strict numeric type checking (rejects
```
bool
```
,
```
NaN
```
,
```
Inf
```
)
All string values from result files are sanitized (truncated, control characters stripped) before surfacing them
Config paths interpolated into shell commands are validated against a safe-character allowlist and escaped with
```
shlex.quote()
```

```
sweep_generator.py
```
读取
```
--base-config
```
指定的单个基础配置文件（JSON），并将生成的配置写入
```
--output-dir
```
```
result_aggregator.py
```
对每个结果文件强制执行10MB大小限制、最大JSON嵌套深度，并严格检查数值类型（拒绝
```
bool
```
、
```
NaN
```
、
```
Inf
```
）
结果文件中的所有字符串值在展示前都会被清理（截断、去除控制字符）
插入到shell命令中的配置路径会验证是否符合安全字符列表，并使用
```
shlex.quote()
```
进行转义

Tool Restrictions

工具限制

Read: Used to inspect script source, references, base configs, and campaign status files
Write: Used to save generated sweep configs, campaign manifests, and aggregated results; writes are scoped to the user's working directory
Grep/Glob: Used to locate campaign files, result files, and search references
The skill's
```
allowed-tools
```
excludes
```
Bash
```
to prevent the agent from executing arbitrary commands when processing untrusted simulation outputs

读取：用于检查脚本源码、参考文档、基础配置和任务状态文件
写入：用于保存生成的扫描配置、任务清单和汇总结果；写入操作仅限于用户的工作目录
Grep/Glob：用于定位任务文件、结果文件和搜索参考文档
技能的
```
allowed-tools
```
排除了
```
Bash
```
，防止代理在处理不可信模拟输出时执行任意命令

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
Command templates are validated but never executed by the skill itself; execution is the user's responsibility

不使用
```
eval()
```
、
```
exec()
```
或动态代码生成
所有子进程调用使用显式参数列表（不使用
```
shell=True
```
）
减少工具范围（无Bash），限制代理仅执行读写操作
命令模板会被验证，但技能本身从不执行命令；执行由用户负责

Limitations

局限性

Not a job scheduler: Does not submit jobs to SLURM/PBS; generates configs and tracks status
No parallel execution: User must run simulations externally (can use GNU parallel, SLURM, etc.)
File-based tracking: Status tracked via files; no database or real-time monitoring
Local filesystem: Assumes all files accessible from local machine

不是任务调度器：不会将任务提交到SLURM/PBS；仅生成配置并跟踪状态
不支持并行执行：用户需在外部运行模拟（可使用GNU parallel、SLURM等工具）
基于文件的跟踪：通过文件跟踪状态；无数据库或实时监控
本地文件系统：假设所有文件均可从本地机器访问

References

参考文档

```
references/campaign_patterns.md
```
- Common campaign structures
```
references/sweep_strategies.md
```
- Parameter sweep design guidance
```
references/aggregation_methods.md
```
- Result aggregation techniques

```
references/campaign_patterns.md
```
- 常见任务结构
```
references/sweep_strategies.md
```
- 参数扫描设计指引
```
references/aggregation_methods.md
```
- 结果汇总技术

Version History

版本历史

See

CHANGELOG.md

for the authoritative, dated history. Summary:

v1.1.3 (2026-06-24): Added a Verification checklist and a Common pitfalls & rationalizations section grounded in the scripts' real behavior (result-file-only "completed" detection, silent skip of unreadable metrics, minimize-by-default direction, key-path merge semantics)
v1.1.1 (2026-06-23): Dot-notation nested overrides in
```
sweep_generator.py
```
, input-validation hardening (
```
--params
```
name/finite/count caps,
```
--samples
```
bounds), documented
```
--maximize
```
and the
```
list
```
action, corrected Script Outputs table and worked-example numbers
v1.1.0 (2026-03-26): Standardized metadata, evaluation suite, security review, CHANGELOG
v1.0.0 (2026-02-25): Initial release with sweep, campaign, tracking, and aggregation

详见

CHANGELOG.md

获取权威的日期化历史记录。摘要：

v1.1.3（2026-06-24）：新增验证清单和常见误区与合理化借口部分，内容基于脚本实际行为（仅通过结果文件判断“完成”、静默跳过无法读取的指标、默认最小化方向、键路径合并语义）
v1.1.1（2026-06-23）：
```
sweep_generator.py
```
支持点符号嵌套覆盖，强化输入验证（
```
--params
```
名称/有限性/数量上限、
```
--samples
```
范围），文档化
```
--maximize
```
和
```
list
```
操作，修正脚本输出表格和示例数值
v1.1.0（2026-03-26）：标准化元数据、评估套件、安全审查、CHANGELOG
v1.0.0（2026-02-25）：初始版本，包含扫描、任务、跟踪和汇总功能