Unified workflow for TGV experiments: eps sweep, sfreq sweep, and energy-ratio analysis. Submits SLURM jobs, monitors progress, generates diagnostic plots.
每个工作流包含：清理旧数据 → 构建 → 提交 SLURM 任务 → 监控进度 → 生成诊断图表
| 工作流 | 触发场景 | 详细步骤 |
|---|---|---|
| tgv-eps | eps 扫描、噪声敏感性、FT_EPS | references/eps-workflow.md |
| tgv-sfreq | sfreq 扫描、谱滤波、FT_SFREQ | references/sfreq-workflow.md |
| tgv-energy-ratio | 能量比分析、谱能量比、VTU 快照 | references/energy-ratio-workflow.md |
触发时先读取对应的 reference 文件，再行动。
所有工作流的 Clean / Build / Monitor 步骤结构相同。
工作目录约定：
tgv_<任务名>（如 tgv_eps、tgv_sfreq、tgv_energy_ratio）<workdir> 表示job_mapping 约定
job_mapping.json，完整记录实验的全部元信息，确保事后可重现和分析。<workdir>/agent/job_mapping.jsonpoe submit 输出提取 job ID 并立即写入sync_workdirs.py 会自动读取 job_mapping.json 并写入 dashboard_task_id 字段，将工作目录与仪表盘任务关联。提交任务后运行 uv run python3 ~/research-dashboard/scripts/sync_workdirs.py 或在仪表盘侧边栏点击 同步目录 即可。也可通过 CLI 操作：uv run python3 ~/research-dashboard/scripts/dash_cli.py sync约定：在 submit 前，征得用户同意后执行 poe clean <workdir> 清空旧数据（如有）。
mkdir -p <workdir>/agent <workdir>/logs
poe clean <workdir> -a
提交任务前确保可执行文件与源码一致：
poe build --hpc
轮询进度文件（后缀格式 {job_id}_{task_id}）：
cat <workdir>/progress_<jobid>_<taskid>.json
squeue -u $USER --format="%.10i %.8T %.10M"
文件中 "done": true 或文件消失表示该 task 完成。
eps 和 sfreq 工作流均通过 poe submit 的通用扫描参数提交 SLURM array job：
poe submit <workdir> \
--sweep-arg <ARG> \ # run.py 的 CLI 参数名，如 --eps 或 --sfreq
--sweep-func '<EXPR>' \ # bc -l 表达式，x = SLURM_ARRAY_TASK_ID
--array 0-<M> \ # SLURM array 范围
--size <N>
SWEEP_FUNC 使用 bc -l 求值，变量 x 为 task_id。bc 函数名：e(x) = exp(x)，l(x) = ln(x)，sqrt(x) = 开方。
示例：
| 场景 | SWEEP_ARG | SWEEP_FUNC | array | 结果 |
|---|---|---|---|---|
| eps 等差 | --eps | 0.04*x | 0-4 | 0, 0.04, 0.08, 0.12, 0.16 |
| sfreq 等差 | --sfreq | 32+32*x | 0-4 | 32, 64, 96, 128, 160 |
| sfreq 含 off | --sfreq | 32+32*x | 0-5 | 32..192，其中某个 task 的 SWEEP_FUNC 算出 0 即为 off |
| sfreq-coeff 扫 c | --sfreq-coeff | x | 0-8 | c=0(基线)..8，FT_SFREQ=round(c·log₂(N)) |
| 参数 | 值 | 说明 |
|---|---|---|
| T_C | 1/π ≈ 0.3183 | 对流时间单位：MESH_BOX_LENGTH/(2π)/V = 2/(2π)/1（与 tgv/plot.py 一致） |
| 项目根目录 | $PROJECT_ROOT | 所有命令均在此运行 |
SKILL_DIR=.agents/skills/tgv-workflows/scripts 中的脚本完成，其用法在对应的 reference 文件中有详细说明。自动归档：绘图脚本若检测到输出文件已存在，会先移动到 <workdir>/agent/archive/ 并附加时间戳，避免覆盖旧结果。
脚本以任务名为前缀：
| 任务 | 脚本 | 用途 |
|---|---|---|
eps | eps_plot_combined.py | eps 时间序列组合图 |
eps | eps_plot_terminal_error.py | 终态误差 vs FT_EPS |
eps | eps_plot_rms.py | RMS 偏差 vs 网格大小 |
sfreq | sfreq_plot_combined.py | sfreq 时间序列组合图 |
sfreq | sfreq_plot_relative_l2_error.py | 相对 L2 误差 vs size |
sfreq | sfreq_plot_contour_by_size.py | L2 误差 vs sfreq + threshold 2×3 图 |
sfreq | sfreq_plot_threshold_by_re.py | 多 Re threshold 交叉点 vs size 1×3 图 |
energy_ratio | energy_ratio_extract.py | VTU → 能量比 CSV |
energy_ratio | energy_ratio_plot2d_by_size.py | 多网格固定时刻 2D PDF |
energy_ratio | energy_ratio_plot2d_by_time.py | 单网格时间演化 2D PDF |
energy_ratio | energy_ratio_plot3d_by_size.py | 多网格固定时刻 3D HTML |
energy_ratio | energy_ratio_plot3d_by_time.py | 单网格时间演化 3D HTML |
科研仪表盘（~/research-dashboard/，端口 8000）自动关联工作目录与研究任务。
提交后同步：提交 SLURM 任务并写入 job_mapping.json 后，运行同步将任务注册到仪表盘：
uv run python3 ~/research-dashboard/scripts/sync_workdirs.py
后处理后注册产出：生成 PDF/HTML 后，通过 CLI 注册产出文件：
uv run python3 ~/research-dashboard/scripts/dash_cli.py artifact <task_id> <文件路径>
添加讨论：记录实验观察或下一步计划：
uv run python3 ~/research-dashboard/scripts/dash_cli.py discuss <task_id> "实验观察内容"
sync_workdirs.py 运行后会在 job_mapping.json 中写入 dashboard_task_id 字段，后续操作可直接使用该 ID 引用对应的仪表盘任务。