itasca-parametric-skill — publishable Claude Code skill

⚠️ 重要依赖说明 — 先看这里再安装

本技能不包含 itasca-mcp 和 itasca-mcp-bridge。它们是 yusong652 的独立项目，需要单独安装。

你需要准备：

1. Itasca 引擎（FLAC3D / PFC3D / 3DEC 等）— 你已有的数值模拟软件
2. itasca-mcp-bridge — 在引擎的嵌入式 Python 中安装并启动：

   import itasca_mcp_bridge; itasca_mcp_bridge.start()

   首次安装指南：https://raw.githubusercontent.com/yusong652/itasca-mcp/main/docs/agentic/itasca-mcp-bootstrap.md
3. itasca-mcp（可选，仅交互模式需要）— uvx itasca-mcp 或 pip install itasca-mcp

本技能只负责"编排流程"（生成工况 → 提交计算 → 汇总结果），不负责"控制引擎"。

A Claude Code skill that turns a recurring Itasca research chore — run a model across a parameter space, collect outputs, see how the response changes — into a standardised, resumable workflow. Built on top of the existing itasca-mcp bridge: this skill does not re-implement Itasca control. The bridge owns the engine connection; this skill is the orchestration layer above it — config, case generation, logs, result aggregation, regression, plotting, and grid-mode calibration.

Supports all Itasca engines the bridge supports: FLAC3D, PFC3D, 3DEC, UDEC, MassFlow, MPoint. The generated per-case engine script is stdlib-only and version-safe across engine 6 / 7 / 9.

What it does

config.yaml + template.dat
   → generate_cases.py    expands the parameter space, renders one folder per case
   → run_study.py         autonomous sweep (talks to the bridge over HTTP)
      *or*                 the agent drives itasca_execute_task per case (interactive)
   → collect_results.py   results.csv + regression report
   → calibrate.py         rank cases vs a target (grid mode)
   → plot.py              plots/*.png

Two execution modes, same generated cases:

• Autonomous sweep — run_study.py submits every pending case to the bridge, polls to completion, captures logs, continues past failures. Fire and forget; resumable.
• Interactive / MCP-driven — the agent calls itasca_execute_task / check_task_status / execute_code per case, reasoning between iterations. Use this for calibration loops and live inspection.

Install / prerequisites

This is a self-contained, relocatable skill directory (the scripts locate their own templates via __file__, so it works from any install path). Install it by placing this directory where your Claude Code looks for skills:

# user-level (recommended — the bridge is machine-scoped)
cp -r itasca-parametric-skill ~/.claude/skills/
# or project-level
cp -r itasca-parametric-skill <project>/.claude/skills/

Restart Claude Code; the skill auto-registers. It needs:

1. The itasca-mcp bridge running inside the Itasca engine GUI — in the engine's IPython console:

   import itasca_mcp_bridge
   itasca_mcp_bridge.start()

   First-time setup (engine install, bridge pip-install, MCP client config): fetch and follow https://raw.githubusercontent.com/yusong652/itasca-mcp/main/docs/agentic/itasca-mcp-bootstrap.md.
2. Host Python 3.10+ with pyyaml, pandas, matplotlib for the skill scripts (pip install -r requirements.txt). The per-case run.py that runs inside the engine is stdlib-only and needs none of these.

Quick start (autonomous sweep)

# 1. author config.yaml + template.dat (copy examples/ as a base)
# 2. generate cases
python scripts/generate_cases.py --config path/to/config.yaml

# 3. run the sweep
python scripts/run_study.py --config path/to/config.yaml

# 4. collect + plot
python scripts/collect_results.py --config path/to/config.yaml
python scripts/calibrate.py    --config path/to/config.yaml   # if a target is set
python scripts/plot.py         --config path/to/config.yaml

Re-running any step is safe — completed cases are skipped, so you can interrupt and resume. Check progress with python scripts/status.py --config ….

Examples

• examples/flac3d_tunnel_sigma3/ — FLAC3D anisotropic tunnel, dip-angle sweep, crown-displacement + unbalanced-ratio extraction. Single parameter with two expr-derived parameters.
• examples/pfc3d_ucs_fric/ — PFC3D bonded-ball block, 2-parameter (friction × stiffness) Cartesian sweep, plus a commented calibration target.

Documentation

• SKILL.md — the orchestration guide the agent follows
• references/mcp_tools.md — itasca-mcp tool signatures + response envelope (for interactive mode)
• references/config.md — full config.yaml reference

Design notes (why it's shaped this way)

• No subprocess / no license / no stdout parsing in the skill. The bridge already solves those. This skill is purely the research-workflow layer.
• Per-case run.py reads model.dat and replays it via itasca.command(...), never program call. On engine 6/7 and 9.0–9.6, program call '<file>.dat blocks the bridge for the file's whole duration; the replay approach is version-safe and preserves per-command output and error locality.
• FISH extraction via fish define + call_function. Itasca 9's itasca.fish has no eval, so each extract: expression is wrapped as a throwaway zero-arg FISH function and called — any intrinsic works.
• No closed-loop optimizer in v1. Calibration is grid ranking + the agent refining the grid between runs. A scipy.optimize-backed closed loop is a documented future extension; v1 keeps the user in control of every model change, which suits the small parameter counts typical of geomechanics.