開発コマンド (Development Commands)

日常の開発で使うコマンドの一覧．コマンドを推測せず必ず本ファイルを参照する（新しく確定・変更された時は本ファイルに反映する）．

※ Git Bash ではログの日本語が文字化けする．先頭に PYTHONIOENCODING=utf-8 を付けると正しく表示される．

環境 (Environment)

データ (Data)

実データ（サーバ上）での実行例（GPU を使わないので --cpu）:

uv run tias-remote run --name manifest --cpu --server Newton -- tias-dataset build-manifest --config configs/newton.yaml
uv run tias-remote run --name survey --cpu --server Newton -- tias-dataset survey --config configs/newton.yaml
uv run tias-remote logs survey          # 最後の行に実験 ID が出る
uv run tias-remote pull <実験ID>          # 集計値と図だけが手元の runs/ に届く

設定ファイルは configs/synthetic.yaml（手元の合成データ）と configs/newton.yaml（サーバの実データ）．環境変数 TIAS_DATA_ROOT を設定すると data.root より優先される．

リモート実行 (Remote Execution)

研究室の GPU サーバ（Newton・Archimedes）で計算するときは tias-remote を使う．コマンドはすべて手元で実行する．空いている GPU を両サーバから自動で選ぶ（未使用の GPU を最優先．仕様は SPEC_03）．サーバ設定は configs/remote.yaml．

• gpus・run・status は GPU を 10 秒観測してから判定するため，1 回に 13 秒ほどかかる．急ぐときは --observe 0（瞬間値のみ．約 2 秒．gpus・run のみ）
• run は起動前に選んだサーバへ自動でコードを送る（--no-push で省略）．ジョブには CUDA_VISIBLE_DEVICES・TIAS_DATA_ROOT（そのサーバのデータの場所）が渡る
• pull は回収ホワイトリストに名前が一致するファイルだけを runs/<実験ID>/ に持ち帰る．回収しなかったファイルは件数だけ表示される
• ジョブログはサーバ上の runs/_remote_logs/<ジョブ名>.log．末尾に === [日時] exit <終了コード> の行が付く
• 研究室 LAN 内にいるときは踏み台が不要なので，環境変数 TIAS_REMOTE_JUMP を空文字にすると速い（Git Bash: TIAS_REMOTE_JUMP= uv run tias-remote gpus．PowerShell: $env:TIAS_REMOTE_JUMP = ""）
• ジョブの実行中に同じサーバへ push しない（上書き展開なので，実行中のジョブが新旧のコードを混ぜて読むおそれがある．実行中なら警告が出る）
• 各サブコマンドの詳細は uv run tias-remote <サブコマンド> --help

学習・交差検証 (Training)

設定ファイル:

サーバでの実行例:

# 1 本だけ（空いている GPU を自動で選ぶ）
uv run tias-remote run --name cv1 -- tias-train cv --config configs/cv_with_mild.yaml

# 複数本を同じ GPU で順に回す（キュー）．; で区切るので 1 本が失敗しても次へ進む
uv run tias-remote run --name q1 --server Archimedes --gpu 1 -- bash -c "tias-train cv --config configs/cv_with_mild.yaml; tias-train cv --config configs/cv_effb0_with_mild.yaml;"

uv run tias-remote logs q1              # 各実験の最後の行に実験 ID が出る
uv run tias-remote pull <実験ID>         # 指標・図・ログだけが手元の runs/ に届く

• ConvNeXt-Tiny の 5-fold 交差検証 1 本は Archimedes の RTX A6000 で約 2.5 分（2026-09-28 実測．画像の読み込み約 8 秒を含む）
• 事前学習の重みは初回にサーバが Hugging Face からダウンロードする（~/.cache/huggingface）
• ログに出る lr_scheduler.step() before optimizer.step() の警告は，混合精度で最初の数ステップの勾配がオーバーフローして捨てられたときに出るもので無害

テスト (Test)

臨床データに依存するテストは書かない（合成データで動くテストのみ）．

Lint / Format

※ .claude/ はテンプレート所有のため ruff の対象外（pyproject.toml の extend-exclude）．テンプレート由来のフックのテストは uv run pytest .claude/hooks/tests で実行する．

フック (Hooks)