hpc-runtime-doctor

HPC Runtime Doctor

目標

クラスターで発生した症状を、リソース配置の診断、環境チェックリスト、安全な再試行計画に変換します。

要件

• Python 3.10+
• 外部依存関係なし
• Linux、macOS、Windows で動作

収集する入力

入力	説明	例
スケジューラー	SLURM、PBS、LSF、ローカル	slurm
ノード／タスク／スレッド	実行時の配置	2 nodes, 128 tasks, 2 threads
GPU	--gpus で指定する合計（ジョブ全体）の GPU 数、または --gpus-per-node で指定するノードあたりの GPU 数	--gpus 4 または --gpus-per-node 1
症状	観測された障害	oom,killed,slow-gpu
MPI／OpenMP／GPU の使用	並列化モード	mpi+openmp+gpu
実行時間	要求する時間	12:00:00
スクラッチ領域	スクラッチ領域を使用するかどうか	true

判断の指針

• 物理設定を変更する前に、リソース配置を確認してください。
• ソルバーの動作をデバッグする前に、モジュール／コンパイラー／MPI／CUDA の整合性を確認してください。
• 再開ファイルの欠落やスクラッチ領域のクリーンアップは、物理計算の失敗ではなく、ワークフローの失敗として扱ってください。
• GPU ジョブでは、実行ファイルが要求したアクセラレーターのバックエンドを有効にしてビルドされていることを確認してください。

スクリプトの出力

scripts/hpc_runtime_doctor.py は次の項目を出力します。

• resource_layout（tasks_per_node、total_cpus、合計 gpus、gpus_per_node を含みます）
• diagnoses
• environment_checks
• retry_plan
• scheduler_notes
• warnings（GPU あたりのランク数の過剰割り当て、OpenMP／スレッド数の不一致、タスク配置の不均等などのレイアウトに関する警告）

デフォルト（非 JSON）モードでは、スクリプトはリソース配置の概要、warnings、環境チェック、再試行計画も出力するため、特に重要な項目が隠れることはありません。

ワークフロー

--gpus は GPU の合計数（ジョブ全体）を指定します。ノードあたりの割り当て数が分かっている場合は --gpus-per-node（SLURM の --gres=gpu:N と同じ意味）を使用します。この場合、GPU の合計数は gpus_per_node * nodes となり、--gpus の指定より優先されます。

python3 skills/hpc-deployment/hpc-runtime-doctor/scripts/hpc_runtime_doctor.py \
  --scheduler slurm \
  --nodes 2 \
  --tasks 128 \
  --cpus-per-task 2 \
  --gpus 4 \
  --symptoms oom,slow-gpu \
  --uses-mpi \
  --uses-openmp \
  --uses-gpu \
  --json

上の例では、128 個のランクを 4 基の GPU に割り当てています（GPU あたり 32 ランク）。そのため、warnings の一覧には Many MPI ranks per GPU (32.0 ranks/GPU) may reduce GPU efficiency. という警告が表示されます。GPU あたりのランク数は、GPU の合計数に対するランクの合計数を使って確認されるため、複数ノードのジョブでも正しく判定されます（しきい値は GPU あたり 16 ランクです）。

エラー処理

無効なリソース数が指定されると、終了コード 2 で停止します。不明な症状はカスタム項目として保持され、人による確認に回されます。

制限事項

このスキルは実行中のスケジューラーに問い合わせません。送信されたレイアウトと症状に基づいて診断します。

検証チェックリスト

• スクリプトの resource_layout ブロックを記録し、tasks_per_node が整数（小数値ではない）であること、および total_cpus が tasks * cpus_per_task と等しいことを確認しました。tasks_per_node が小数値の場合は、再試行前に不均等配置の警告を確認しました。
• GPU ジョブでは、確定した GPU の合計 gpus（および設定されている場合は gpus_per_node）を記録し、GPU あたりのランク数 = tasks / gpus を計算しました。その値が GPU あたり 16 ランクのしきい値以下であること、または表示された Many MPI ranks per GPU 警告を意図的に許容することを確認しました。
• warnings の各項目（cpus_per_task=1 での OpenMP 使用、GPU を要求しているのに GPU が 0 基、tasks < nodes、不均等配置、大量 I/O 向けジョブでのスクラッチ領域使用）を確認し、無視せずにそれぞれ解決または妥当性を確認しました。
• environment_checks の項目について、実際の成果物として確認を完了しました。モジュール一覧、実行ファイルのパス／バージョン、MPI ランチャーとライブラリの一致、アクセラレーターのビルドフラグ（CUDA／Kokkos／OpenMP）、スケジューラーの標準出力／標準エラーを取得しました。
• 観測された各症状を diagnoses の項目に対応付け、未対応の症状が custom カテゴリーに入っていないことを確認しました（custom の各項目について、人による確認用に標準エラー／標準出力／モジュール一覧／コマンドラインをすべて収集しました）。
• retry_plan に従い、再現に必要な最小ケースを再実行し、リソース変数を 1 つだけ変更し、再開／チェックポイント機能を有効にして、スケジューラースクリプトと環境のスナップショットを結果とともに保存しました。

よくある落とし穴と誤った正当化

つい選びがちな近道	それが間違っている理由／すべきこと
「クラッシュせずに実行できたので、レイアウトは問題ありません。」	実行が完了したからといって、正しいとは限りません。warnings リストと resource_layout を確認してください。過剰割り当て、不均等な配置、GPU のアイドル状態は、クラッシュしなくても結果をひそかに遅くしたり、破損させたりする可能性があります。
「ノードごとのランク数が GPU 数に収まっているので、過剰割り当てはありません。」	過剰割り当てはノードごとではなく、全ランク数を全 GPU 数で割って判断します。このスクリプトは tasks / gpus を計算します。複数ノードのジョブでは、単位を揃えたチェックでしか検出できない高いランク/GPU 値が見えにくくなることがあります。
「--gpus を渡したので、ノードごとの GPU 数は関係ありません。」	--gpus はジョブ全体の合計です。クラスターがノードごとに割り当てる場合は、--gpus-per-node（SLURM --gres=gpu:N）を使用してください。これは --gpus を上書きし、合計は gpus_per_node * nodes になります。取り違えると、ランク/GPU の報告が誤ります。
「ジョブが強制終了されたので、物理演算またはソルバーのバグです。」	killed／oom／timeout は、物理演算ではなくスケジューラーとリソースのカテゴリです。シミュレーションパラメーターを変更する前に、標準出力／標準エラーから実行時間、メモリ制限、プリエンプションを確認してください。
「原因不明の症状はルールにないので、無視してかまいません。」	原因不明の症状は何もしないのではなく、custom の診断になります。人が確認できるよう、スケジューラーの標準エラー／標準出力、モジュール一覧、コマンドラインを収集してください。何も起きていないことは、問題がない証拠にはなりません。
「ランク、スレッド、ビルドをまとめて変更すれば、より早く解決できます。」	複数の変数を同時に変更すると、失敗の原因を診断できなくなります。retry_plan では、最小の再現ケースで一度に 1 つの変数だけを変更するよう定めています。

セキュリティ

入力の検証

• 入力はスカラー形式の CLI 値とブール値のみで、自由形式のコードパスはありません。
• リソース数（--nodes、--tasks、--cpus-per-task、--gpus、--gpus-per-node） は整数として検証されます（ブール値は拒否）。非負かつ有限であることが求められ、 上限は 1,000,000 です。さらに、--nodes、--tasks、--cpus-per-task は 1 以上である必要があります。範囲外、整数以外、またはゼロの値が指定された場合は、コード 2 で終了します。
• --symptoms 文字列は、最大 64 個のカンマ区切り項目に制限され、各項目は最大 64 文字です。 --walltime は最大 32 文字です。サイズの上限を超える入力は、コード 2 で終了します。
• 症状は分割、トリミングされ、小文字に変換されます。不明な症状は拒否されず、人が確認できるよう custom の診断として保持されます。
• --scheduler は自由形式の文字列として受け付けられ、許可リストとの照合は行われません。 リソースレイアウトにそのまま出力されるだけです。

ファイルアクセス

• このスクリプトはファイルの読み書きを行いません。I/O は CLI 引数を受け取り、標準出力に出力する （--json を指定した場合はインデント付き JSON、それ以外の場合は人が読める要約）だけです。 エラーは標準エラーに出力されます。
• パスを受け取ったり開いたりしないため、ファイルシステムを探索される危険性はなく、 パスのサンドボックス化に関する懸念もありません。

ツールの制限

• allowed-tools は Read, Bash, Write, Grep, Glob です。
• Bash は、同梱の scripts/hpc_runtime_doctor.py の実行にのみ使用されます。
• Read、Grep、Glob は、スキル自体のファイルと、ユーザーが指定したログや 提出スクリプトの調査に使用されます。Write は、依頼された場合に診断メモや 再試行プランを記録するために使用されます。

安全対策

• eval、exec、os.system、subprocess は使用しません。このスクリプトはスケジューラーや 外部プロセスを起動せず、環境変数も調べません。
• 引数の解析には argparse を使用し、機械可読な出力は JSON として出力します。
• サービス拒否攻撃への影響は、リソース数の上限（1,000,000）、症状の上限 （64 項目 × 64 文字）、および実行時間の上限（32 文字）によって抑えられています。

参考資料

• スケジューラーとランタイムの診断パターンについては、references/hpc_runtime_patterns.md を参照してください。

バージョン履歴

• 1.1.3：resource_layout、warnings、ランク数／GPU、environment_checks、diagnoses、retry_planに関連付けられた、エビデンスに基づく項目を含む検証チェックリストと、よくある落とし穴と合理化の表を追加しました。
• 1.1.1：識別力のある評価を追加しました。各ケースで、決定論的なscript_checksを使用して、スクリプト固有の出力（GPUあたりのランク数に関する正確な警告、診断カテゴリ、リソースレイアウトのフィールド）を指定するようになりました。
• 1.1.0：単位に一貫性のあるGPUあたりのランク数に関する警告（合計ランク数／合計GPU数）、新しい--gpus-per-node引数、不均等な配置に関する警告を伴う整数のtasks_per_node、人が読みやすい完全な（JSONではない）出力、およびリソース数、症状、ウォールタイムの入力上限を追加しました。
• 1.0.0：HPCランタイム診断スキルの初期版です。