hpc-simctl 0.1.3

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 定義
  campaign.toml        # 研究意図 (仮説・変数・観測量)
  .gitignore           # 大容量出力の除外設定
  CLAUDE.md            # Claude 向け AI エージェント指示
  AGENTS.md            # Codex / 汎用 Agent 向け AI エージェント指示
  cases/               # Case 定義の格納場所
  runs/                # run の格納場所
  refs/                # シミュレータリファレンスリポジトリ
  tools/
    hpc-simctl/        # simctl 本体 (editable install, Git 管理外)
  .venv/               # Python 仮想環境 (Git 管理外)
  refs/
    knowledge/         # 外部知識ソースのマウントポイント
      shared-lab-kb/   # git/path で接続した共有知識リポジトリ
  .simctl/             # 知識層 (ナレッジ・環境・知見)
    knowledge/         # 自動生成ナレッジ (gitignore 対象)
      enabled/         # 有効な profile の imports.md
    insights/          # 実験知見 (人間向け Markdown)
    facts.toml         # 構造化された知識 (AI 向け machine-readable claims)
    environment.toml   # 実行環境記述 (自動検出)
    links.toml         # 他プロジェクトへの参照

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 の定義

cases/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 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 sweep runs/cavity/scan

7. Job の投入

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

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

8. 状態の確認

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

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

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

コマンドリファレンス

プロジェクト管理

コマンド	説明
simctl init [SIMS...] [-y]	プロジェクトの初期化 (対話型がデフォルト)
simctl doctor [PATH]	環境検査 (設定・sbatch・run_id 一意性・環境検出)
simctl config show	設定表示
simctl config add-simulator	シミュレータ追加 (対話型)
simctl config add-launcher	ランチャー追加 (対話型)

Run 作成・投入

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

状態管理・モニタリング

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

解析・整理

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

知識管理

コマンド	説明
simctl update	シミュレータパッケージのアップグレード
simctl update-refs [SIMS...]	refs/ リポジトリ更新 + ナレッジインデックス再生成
simctl knowledge save NAME	知見を .simctl/insights/ に保存
simctl knowledge list	知見一覧表示
simctl knowledge list --sources	外部知識ソース一覧表示
simctl knowledge show NAME	知見の詳細表示
simctl knowledge attach TYPE NAME URL	外部知識ソースを接続 (git / path)
simctl knowledge detach NAME	外部知識ソースを切断
simctl knowledge sync [NAME]	知識ソース同期 + リンク先から知見をインポート
simctl knowledge render	有効な profile から imports.md を生成
simctl knowledge status	知識統合の状態表示
simctl knowledge links	プロジェクトリンク一覧
simctl knowledge add-fact CLAIM	構造化された知識を facts.toml に追加
simctl knowledge facts	構造化知識の一覧表示

知識管理は三層構造:

• source knowledge — 外部共有知識リポジトリ (refs/knowledge/ にマウント)
• local knowledge — プロジェクト固有の知見 (insights, facts, links)
• 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 / doctor
        new.py             # new (ケーススキャフォールド)
        create.py          # create / sweep
        submit.py          # run (sbatch 投入)
        status.py          # status / sync
        log.py             # log (stdout 表示)
        jobs.py            # jobs (実行中ジョブ一覧)
        history.py         # history (投入履歴)
        list.py            # list
        clone.py           # clone
        extend.py          # extend (継続 run)
        analyze.py         # summarize / collect
        manage.py          # archive / purge-work
        update.py          # update (パッケージ更新)
        update_refs.py     # update-refs (refs/ 更新 + ナレッジ)
        knowledge.py       # knowledge (知見管理)
        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, links)
        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 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

ドキュメント

• はじめに (Getting Started) -- チュートリアル形式のウォークスルー
• アーキテクチャ -- システム設計とモジュール構成
• 拡張ガイド -- Adapter / Launcher の追加方法
• 知識層 -- AI エージェント向け知識管理アーキテクチャ
• TOML リファレンス -- 全設定ファイルのフィールド定義
• SPEC.md -- 完全な仕様書

ライセンス

Apache-2.0