hpc-simctl 0.1.7

HPC simulation run management CLI tool for Slurm-based environments

hpc-simctl

HPC 環境における Slurm ベースのシミュレーション実行管理 CLI ツール。

run ディレクトリを日常運用の主単位とし、パラメータサーベイ展開・job 投入・状態追跡・provenance 記録・解析補助を一貫して管理します。

特徴

• run 中心の管理: すべての操作は run ディレクトリ (runs/.../Rxxxx/) を基点に行う
• パラメータサーベイ: survey.toml による parameter sweep の自動展開（直積生成）
• Slurm 連携: sbatch による job 投入、squeue/sacct による状態同期
• Simulator Adapter: シミュレータ固有処理を Adapter パターンで抽象化。core はシミュレータに依存しない
• Launcher Profile: srun / mpirun / mpiexec の起動方式を Profile で切替可能
• Provenance 記録: git commit、executable hash、パラメータ snapshot を manifest.toml に自動記録
• 多重ネスト対応: runs/ 以下を自由に階層化して分類・整理できる
• Agent/AI 対応: TOML/JSON ベースの構造化データで AI エージェントとの連携が容易
• 知識層: シミュレータ知識・実行環境・研究意図の 3 層で AI エージェントにコンテキストを提供
• 外部知識ソース: 共有知識リポジトリを project に接続し、profile ベースで必要な知識だけを投影
• パラメータバリデーション: 物理的制約 (CFL 条件, Debye 長等) を run 生成前にチェック
• Research Campaign: campaign.toml で研究仮説・変数・観測量を構造化し、実験設計を明示

インストール

simctl はプロジェクトごとにブートストラップインストールされます。 事前のグローバルインストールは不要で、uv だけあれば始められます。

# プロジェクトディレクトリを作成して初期化 (uv だけあれば OK)
uvx --from hpc-simctl simctl init

# activate して利用開始
source .venv/bin/activate
simctl doctor

simctl init が以下を自動的に行います:

1. .venv/ を作成 (uv venv)
2. tools/hpc-simctl/ に simctl リポジトリを clone
3. simctl を .venv に editable install (uv pip install -e)
4. シミュレータ固有パッケージをインストール

simctl の更新は cd tools/hpc-simctl && git pull で行えます。

既存プロジェクトのセットアップ

uvx --from hpc-simctl simctl setup https://github.com/user/my-project.git
source my-project/.venv/bin/activate
simctl doctor

開発者向け (hpc-simctl 自体の開発)

git clone https://github.com/Nkzono99/hpc-simctl.git
cd hpc-simctl
uv sync --dev

クイックスタート

1. プロジェクトの初期化

上記のインストール手順を実行すると、以下のファイル・ディレクトリが生成されます:

my-simulation-project/
  simproject.toml      # プロジェクト設定
  simulators.toml      # シミュレータ定義
  launchers.toml       # Launcher Profile 定義
  SITE.md              # site profile 由来の companion doc (生成物)
  campaign.toml        # 研究意図 (仮説・変数・観測量)
  .gitignore           # 大容量出力の除外設定
  CLAUDE.md            # 現在の標準 Agent ハーネス (Claude Code) 向け指示
  AGENTS.md            # CLAUDE.md と同内容の補助ミラー
  .claude/
    settings.json      # Claude Code の team-shared permission / hook 設定
    hooks/             # submit 承認・保護パス監視 hook
    rules/             # project 固有の運用ルール
    skills/            # 定型作業用 SKILL
  cases/               # Case 定義の格納場所
  runs/                # run の格納場所
  refs/                # シミュレータリファレンス / 外部知識ソース
    MPIEMSES3D/        # Adapter が参照する simulator docs
    beach/             # Adapter が参照する simulator docs
    knowledge/         # 外部知識ソースのマウントポイント
      shared-lab-kb/   # git/path で接続した共有知識リポジトリ
  tools/
    hpc-simctl/        # simctl 本体 (editable install, Git 管理外)
  .venv/               # Python 仮想環境 (Git 管理外)
  .simctl/             # 知識層 (ナレッジ・環境・知見)
    knowledge/         # 自動生成ナレッジ (gitignore 対象)
      enabled/         # 有効な profile の imports.md
    insights/          # 実験知見 (人間向け Markdown)
    facts.toml         # 構造化された知識 (AI 向け machine-readable claims)
    environment.toml   # 実行環境記述 (自動検出)

simctl init が生成する Claude ハーネスは、.claude/settings.json と .claude/hooks/ により次のようなガードを入れます。

• manifest.toml、runs/**/input/**、submit/job.sh、work/**、SITE.md などの生成物は直接編集しない
• .simctl/facts.toml や .simctl/insights/ は simctl knowledge save / add-fact 経由で更新する
• simctl runs submit は --dry-run を除き実行前に確認を挟む

hpc-simctl 自体の開発では、Claude ハーネスの定義は src/simctl/harness/claude.py にまとまっています。

2. 研究意図の定義 (campaign.toml)

プロジェクトルートに campaign.toml を作成し、何を調べたいかを記述:

[campaign]
name = "parameter-sensitivity"
description = "格子サイズと時間刻みの感度解析"
hypothesis = "nx=512 以上で解が収束する"
simulator = "my_solver"

[variables]
"nx" = { role = "independent", range = [128, 1024], unit = "cells" }
"dt" = { role = "independent", range = [1.0e-9, 1.0e-7], unit = "s" }

[observables]
max_field = { source = "work/output.h5", description = "最大電場強度" }

AI エージェントはこのファイルを読んで survey 設計や結果解釈に活用します。

3. シミュレータと Launcher の設定

simulators.toml にシミュレータを定義 (シミュレータ指定で init した場合は自動生成):

[simulators.my_solver]
adapter = "generic"
resolver_mode = "local_executable"
executable = "/path/to/solver"

launchers.toml に Launcher Profile を定義:

[launchers.slurm_srun]
kind = "srun"
command = "srun"
use_slurm_ntasks = true

4. Case の定義

simctl case new で case を生成し、cases/<simulator>/<case>/case.toml を編集します:

simctl case new my_case -s my_solver

生成された cases/my_solver/my_case/case.toml の例:

[case]
name = "my_case"
simulator = "my_solver"
launcher = "slurm_srun"
description = "基本ケース"

[classification]
model = "cavity"
submodel = "rectangular"
tags = ["baseline"]

[job]
partition = "compute"
nodes = 1
ntasks = 32
walltime = "12:00:00"

[params]
nx = 256
ny = 256
dt = 1.0e-8

5. 単一 run の作成

simctl runs create my_case --dest runs/cavity/test

6. パラメータサーベイの実行

runs/cavity/scan/survey.toml を作成:

[survey]
id = "S20260327-scan"
name = "parameter scan"
base_case = "my_case"
simulator = "my_solver"
launcher = "slurm_srun"

[axes]
nx = [128, 256, 512]
dt = [1.0e-8, 1.0e-9]

[naming]
display_name = "nx{nx}_dt{dt}"

[job]
partition = "compute"
nodes = 1
ntasks = 32
walltime = "12:00:00"

simctl runs sweep runs/cavity/scan

7. Job の投入

# cwd の run を投入
cd runs/cavity/test/R20260327-0001
simctl runs submit

# survey 内の全 run を一括投入
cd runs/cavity/scan
simctl runs submit --all

8. 状態の確認

# 単一 run の状態確認
simctl runs status R20260327-0001

# Slurm 状態を manifest に同期
simctl runs sync R20260327-0001

# run の一覧表示
simctl runs list
simctl runs list runs/cavity/scan

コマンドリファレンス

プロジェクト管理

コマンド	説明
simctl init [SIMS...] [-y]	プロジェクトの初期化 (対話型がデフォルト)
simctl setup [URL]	既存 simctl project のセットアップ
simctl doctor [PATH]	環境検査 (設定・sbatch・run_id 一意性・環境検出)
simctl context [DIR]	Agent 向け project context の要約を表示
simctl config show	設定表示
simctl config add-simulator	シミュレータ追加 (対話型)
simctl config add-launcher	ランチャー追加 (対話型)
simctl update	シミュレータパッケージのアップグレード
simctl update-refs [SIMS...]	refs/ リポジトリ更新 + ナレッジインデックス再生成

Run 作成・投入

コマンド	説明
simctl case new CASE	新規 case のスキャフォールド生成
simctl runs create CASE	case から単一 run を生成
simctl runs sweep [DIR]	survey.toml からパラメータ直積で全 run 一括生成
simctl runs submit [RUN]	run を sbatch で投入
simctl runs submit --all [DIR]	created な run を一括投入
simctl runs clone	run 複製・派生
simctl runs extend	スナップショットから継続 run 生成

状態管理・モニタリング

コマンド	説明
simctl runs status [RUN]	run の状態確認
simctl runs sync [RUN]	Slurm 状態を manifest.toml に反映
simctl runs log [RUN]	最新 job の stdout/stderr 表示 + 進捗%
simctl runs jobs [PATH]	プロジェクト内の実行中ジョブ一覧
simctl runs history [PATH]	投入履歴表示
simctl runs list [PATH]	run の一覧表示 (状態・タグでフィルタ可能)

解析・整理

コマンド	説明
simctl analyze summarize [RUN]	Adapter による run 解析 summary 生成
simctl analyze collect [DIR]	survey 内の全 run から集計データ生成
simctl analyze plot [DIR]	survey 集計結果の可視化
simctl runs archive [RUN]	run のアーカイブ
simctl runs purge-work [RUN]	work/ 内の不要ファイル削除

知識管理

コマンド	説明
simctl knowledge save NAME	知見を .simctl/insights/ に保存
simctl knowledge list	知見一覧表示
simctl knowledge show NAME	知見の詳細表示
simctl knowledge add-fact CLAIM	構造化された知識を facts.toml に追加
simctl knowledge facts	構造化知識の一覧表示
simctl knowledge source list	外部知識ソース一覧表示
simctl knowledge source attach TYPE NAME URL	外部知識ソースを接続 (git / path)
simctl knowledge source detach NAME	外部知識ソースを切断
simctl knowledge source sync [NAME]	知識ソース同期 + insight 取り込み
simctl knowledge source render	有効な profile から imports.md を生成
simctl knowledge source status	知識統合の状態表示

知識管理は三層構造:

• source knowledge — 外部共有知識リポジトリ (refs/knowledge/ にマウント)
• local knowledge — プロジェクト固有の知見 (insights, facts)
• derived knowledge — source と local から生成される派生物 (imports.md 等)

全コマンドは引数省略時にカレントディレクトリをデフォルトとする。

プロジェクト構成

hpc-simctl/
  pyproject.toml
  SPEC.md                  # 詳細仕様書
  CLAUDE.md                # 開発ガイド
  AGENTS.md                # Agent 運用ガイド
  src/
    simctl/
      cli/                 # CLI エントリポイント (typer)
        main.py            # コマンド登録
        init.py            # init / setup / doctor
        new.py             # case new
        create.py          # runs create / runs sweep
        submit.py          # runs submit
        status.py          # runs status / runs sync
        log.py             # runs log
        jobs.py            # runs jobs
        history.py         # runs history
        list.py            # runs list
        clone.py           # runs clone
        extend.py          # runs extend
        analyze.py         # analyze summarize / collect / plot
        manage.py          # runs archive / purge-work
        update.py          # update (パッケージ更新)
        update_refs.py     # update-refs (refs/ 更新 + ナレッジ)
        knowledge.py       # knowledge / knowledge source
        config.py          # config (設定管理)
      core/                # ドメインロジック
        project.py         # Project 読込・検証
        case.py            # Case 読込・展開
        survey.py          # Survey 展開・parameter 直積
        run.py             # Run 生成・run_id 採番
        manifest.py        # manifest.toml 読書き
        state.py           # 状態遷移管理
        provenance.py      # コード provenance 取得
        discovery.py       # runs/ 再帰探索・run_id 一意性検証
        exceptions.py      # ドメイン例外
        validation.py      # パラメータバリデーション
        campaign.py        # campaign.toml 読込
        environment.py     # 実行環境検出・記述
        knowledge.py       # 知識層 (insights, facts)
        knowledge_source.py  # 外部知識ソース管理
      adapters/            # Simulator Adapter
        base.py            # SimulatorAdapter 抽象基底クラス
        registry.py        # Adapter 登録・lookup
        generic.py         # 汎用 Adapter 実装
      launchers/           # Launcher Profile
        base.py            # Launcher 抽象基底クラス
        srun.py            # srun Launcher
        mpirun.py          # mpirun Launcher
        mpiexec.py         # mpiexec Launcher
      jobgen/              # job.sh 生成
        generator.py       # Slurm batch script 生成
      slurm/               # Slurm 連携
        submit.py          # sbatch 投入
        query.py           # squeue / sacct 問合せ
  tests/
  docs/

状態遷移

run は以下の状態遷移に従います:

created --> submitted --> running --> completed
                |           |
                v           v
             failed      failed
                |
                v
            cancelled

completed --> archived --> purged

Note: simctl runs sync は Slurm の観測結果を manifest に反映するため、 ポーリング間隔によっては submitted → completed のように途中状態を飛び越す遷移が発生します。 詳細は SPEC.md を参照してください。

技術スタック

• Python 3.10+
• CLI: typer (click ベース)
• 設定ファイル: TOML (tomli / tomli-w)
• パッケージ管理: uv
• テスト: pytest
• Lint/Format: ruff
• 型チェック: mypy (strict)

開発

# テスト
uv run pytest

# Lint
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

# 型チェック
uv run mypy src/

# CLI 実行 (開発中)
uv run simctl --help

ドキュメント

• AI エージェントではじめる -- simctl init 済み project を Agent と進める最短導線
• AI Agent 運用概念図 -- simctl init 後の project を Agent とどう回すかの全体像
• src 構成ガイド -- src/simctl/ の層構造と adapter / launcher / site 解決の流れ
• アーキテクチャ -- システム設計とモジュール構成
• 拡張ガイド -- Adapter / Launcher の追加方法
• 知識層 -- AI エージェント向け知識管理アーキテクチャ
• TOML リファレンス -- 全設定ファイルのフィールド定義
• SPEC.md -- 完全な仕様書

ライセンス

Apache-2.0