time-stepping

時間ステップ

目標

時間ステップの選択、段階的な増加、監視に加え、出力とチェックポイントの間隔を決めるための信頼性の高いワークフローを提供します。

要件

• Python 3.10+
• 外部依存関係なし（標準ライブラリを使用）

収集する入力情報

入力	説明	例
安定性の上限	CFL／フーリエ数／反応の上限	dt_max = 1e-4
目標 dt	希望する時間ステップ	1e-5
合計実行時間	シミュレーション時間	10 s
出力間隔	出力間の時間	0.1 s
チェックポイントのコスト	チェックポイントの書き込みにかかる時間	120 s

判断の指針

時間ステップの選択

Is stability limit known?
├── YES → Use min(dt_target, dt_limit × safety)
└── NO → Start conservative, increase adaptively

Need ramping for startup?
├── YES → Start at dt_init, ramp to dt_target over N steps
└── NO → Use dt_target from start

段階的に増やす方法

問題の種類	増加ステップ数	初期 dt
滑らかな IC	不要	Full dt
急峻な勾配	5-10	0.1 × dt
相変化	10-20	0.01 × dt
コールドスタート	10-50	0.001 × dt

スクリプトの出力（JSON フィールド）

スクリプト	主な出力
scripts/timestep_planner.py	dt_limit、dt_recommended、ramp_schedule、notes
scripts/output_schedule.py	output_times、interval、count
scripts/checkpoint_planner.py	checkpoint_interval、checkpoints、overhead_fraction、warnings

output_schedule.py の count は終点を含みます。t_start と t_end の両方が含まれるため、count = number_of_intervals + 1 です（例：0.05 間隔で t=0..5 の場合、100 区間で101フレームになります）。

ワークフロー

1. 安定性の上限を確認する - 数値安定性のスキルを使用します
2. 時間ステップを計画する - scripts/timestep_planner.py を実行します
3. 出力をスケジュールする - scripts/output_schedule.py を実行します
4. チェックポイントを計画する - scripts/checkpoint_planner.py を実行します
5. 実行中に監視する - 上限が変化した場合は dt を調整します

会話形式のワークフロー例

ユーザー: 10時間のフェーズフィールドシミュレーションを実行しています。チェックポイントはどのくらいの頻度で作成すればよいですか？

エージェントのワークフロー:

1. 許容できる作業損失に基づいてチェックポイントを計画します：

   python3 scripts/checkpoint_planner.py --run-time 36000 --checkpoint-cost 120 --max-lost-time 1800 --json
   

2. 解釈：30分ごとにチェックポイントを作成し、オーバーヘッドは約6.7%です（解釈表では「許容可能」）。クラッシュ時に失われる作業は最大30分です。

実行前チェックリスト

• 安定性解析で得られた dt の上限を確認する
• 過渡状態からの起動に向けた段階的な増加方法を定める
• 物理的な時間スケールに合った出力間隔を選ぶ
• 再起動リスクに基づいてチェックポイントを計画する
• パラメーター変更後に dt を再評価する

CLI の例

# Plan time stepping with ramping
python3 scripts/timestep_planner.py --dt-target 1e-4 --dt-limit 2e-4 --safety 0.8 --ramp-steps 10 --json

# Schedule output times
python3 scripts/output_schedule.py --t-start 0 --t-end 10 --interval 0.1 --json

# Plan checkpoints for long run
python3 scripts/checkpoint_planner.py --run-time 36000 --checkpoint-cost 120 --max-lost-time 1800 --json

エラー処理

エラー	原因	解決方法
dt-target must be positive	無効な時間ステップ	正の値を使用します
t-end must be > t-start	無効な時間範囲	時間の範囲を確認します
checkpoint-cost must be < run-time	チェックポイントのコストが高すぎます	チェックポイントのサイズを小さくします

解釈の指針

dt の挙動

観察結果	意味	対応
dt が目標値で安定している	良好	続行します
dt が縮小している	安定性の問題	CFL を確認し、目標値を下げます
dt が振動している	安定性が境界的	安全係数を追加します

チェックポイントのオーバーヘッド

オーバーヘッド	許容度
< 1%	非常に良好
1-5%	良好
5-10%	許容可能
> 10%	頻度が高すぎます。間隔を長くしてください

検証チェックリスト

• timestep_planner.py の dt_recommended と dt_limit を記録し、notes フィールドに「Recommended dt exceeds stability limit」という注記がなく、dt_recommended <= dt_limit であることを確認しました。
• 安定性解析（数値安定性スキル：CFL／フーリエ数／反応の制限）から取得し、--dt-limit に渡した実際の dt_limit 値を推測ではなく記録し、パラメーターを変更するたびにプランナーを再実行しました。
• safety <= 1.0 が適用されていること（制限値より低いマージン）を確認し、どの制約が適用されたか把握できるよう、notes 配列（例：「Recommended dt reduced by stability limit」、最小／最大値のクランプ）を記録しました。
• output_schedule.py の count を記録し、エンドポイントを含む値であること（count = intervals + 1、t_start と t_end の両方が存在）を確認しました。これにより、フレーム数や後処理のインデックスが1つずれるのを防ぎます。
• checkpoint_planner.py のチェックポイント interval、method（daly 対 cap）、overhead_fraction を記録し、オーバーヘッド許容表に照らして overhead_fraction <= 0.10（warnings の項目なし）であることを確認しました。
• すべてのスクリプトが終了コード 0 で終了したこと（終了コード 2／標準エラーの ValueError ではないこと）、および引用する dt／間隔／チェックポイントの値が、検証エラーを出力した実行ではなく JSON の results に由来することを確認しました。

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

つい選びがちな近道	それが誤りである理由／対処方法
「陰解法だから、どんな dt でも問題ない。--dt-limit は省略しよう。」	無条件の安定性は精度を意味しません。大きな dt では時間方向の誤差が大きくなり、過渡現象も捉えられません。物理に基づく dt-target を渡し、推奨 dt を時間スケールと照らして再確認してください。
「大きなステップを取るために --safety を 1.0 より大きく設定しよう。」	safety は制限値以下のマージンです。safety > 1.0 にすると安定性制限を超える dt が返されるため、プランナーはこれを拒否します（終了コード 2）。dt-limit の想定値を下げるか、より細かいメッシュを使用してください。
「クラッシュせずに実行できたから、dt は妥当だ。」	実行が完了することと、正しいことは別です。dt_recommended <= dt_limit を確認し、notes 配列を読み、v_max、D、dx、またはスキームが変わるたびに計画をやり直してください。制限値はそれらに応じて変わります。
「出力の count が 1 つ多いように見えるから、最後のフレームを削除しよう。」	count は設計上、エンドポイントを含みます（intervals + 1）。t_start と t_end の両方が実際の出力です。削除すると、最終状態が気づかれないまま失われます。
「作業を失わないよう、毎ステップでチェックポイントを取ろう。」	これでは overhead_fraction が 10% を超え（プランナーが warnings の項目を出力します）、実行時間の大部分がチェックポイントに費やされます。--max-lost-time（上限方式）または --mtbf（Daly 方式）を使い、オーバーヘッドを「許容可能」の範囲内に保ってください。
「モデルはほぼ同じだから、先週の dt／チェックポイント計画を再利用しよう。」	安定性と最適なチェックポイント間隔は、現在の dx、速度／拡散係数、checkpoint-cost、MTBF に依存します。古い数値をコピーするのではなく、現在の値を使って 3 つのスクリプトを再実行してください。

セキュリティ

入力検証

• すべての数値パラメーター（dt-target、dt-limit、safety、t-start、t-end、interval、run-time、checkpoint-cost、max-lost-time）は有限の正の数として検証されます（inf／nan などの非有限値は拒否されます）
• safety は <= 1.0 に制限されます（安全係数は制限値以下の安定性マージンです。1.0 を超える値は拒否されます）
• ramp-steps と preview-steps は上限 1,000,000 の非負整数として検証されます。メモリー使用量を抑えるため、ランプのうちプレビューされる部分だけが実体化されます
• 時間範囲の整合性が強制されます（t-end は t-start より大きく、checkpoint-cost は run-time より小さくなければなりません）

ファイルアクセス

• スクリプトは外部ファイルを読み込みません。すべての入力は CLI 引数で渡されます
• スクリプトは標準出力（JSON 出力）にのみ書き込みます。エージェントが Write ツールを明示的に使用しない限り、ファイルは作成されません

ツールの制限

• Read: スクリプトのソース、参照資料、ユーザー設定ファイルの確認に使用します
• Bash: 3 つの Python 計画スクリプト（timestep_planner.py、output_schedule.py、checkpoint_planner.py）を、明示的な引数リストで実行するために使用します
• Write: 生成した時間ステップ計画またはチェックポイントスケジュールの保存に使用します。書き込みはユーザーの作業ディレクトリ内に限定されます
• Grep/Glob: 関連ファイルの特定と参照の検索に使用します

安全対策

• eval()、exec()、動的なコード生成は使用しません
• すべてのサブプロセス呼び出しでは、明示的な引数リストを使用します（shell=True は使用しません）
• スクリプトで使用するのは Python の標準ライブラリのみです。pickle の読み込みや、信頼できないデータのデシリアライズは行いません
• すべての出力は、シェルで解釈される内容を含まない、決定論的な JSON です

制限事項

• 適応型制御ではありません: 実行時に適応するのではなく、静的なスケジュールを計画します
• 物理特性が一定であることを前提とします: パラメーターが変わった場合は、計画をやり直してください

参考資料

• references/cfl_coupling.md - 複数の安定性制限の組み合わせ
• references/ramping_strategies.md - 起動時の方針
• references/output_checkpoint_guidelines.md - 実行間隔のルール

バージョン履歴

• v1.2.2 (2026-06-24): 3 つの計画スクリプトの実際の出力に基づき、検証チェックリストと、よくある落とし穴および誤った正当化のセクションを追加
• v1.2.0 (2026-06-23): オーバーヘッドとフレーム数に関するドキュメントおよび評価を修正し、出力時刻の浮動小数点誤差の累積を解消。入力検証を強化（チェックポイントコストが実行時間より小さいこと、安全係数が 1.0 以下であること、ランプおよびプレビューのステップ数の上限、有限値チェック）
• v1.1.0 (2024-12-24): ドキュメント、判断の指針、例を改善
• v1.0.0: 3 つの計画スクリプトを含む初回リリース