numerical-integration

数値積分

目的

時間依存シミュレーションにおいて、積分器を選択し、許容誤差を設定し、適応的な時間刻みを管理するための信頼性の高いワークフローを提供します。

要件

• Python 3.10+
• NumPy（一部のスクリプトで使用）
• コア機能には重い依存関係はありません

収集する入力情報

入力	説明	例
問題の種類	ODE/PDE、硬い／非硬い	stiff PDE
ヤコビアンの利用可否	∂f/∂u を計算できますか？	yes
目標精度	希望する誤差レベル	1e-6
制約	メモリ、陰解法の使用可否	implicit OK
時間スケール	特性時間	1e-3 s

選択の指針

積分器の選択

Is the problem stiff?
├── YES → Is Jacobian available?
│   ├── YES → Use Rosenbrock or BDF
│   └── NO → Use BDF with numerical Jacobian
└── NO → Is high accuracy needed?
    ├── YES → Use RK45 or DOP853
    └── NO → Use RK4 or Adams-Bashforth

硬い系と非硬い系の判定

症状	硬い可能性	対応
dt が極端に小さくなる	はい	陰解法に切り替えます
固有値の範囲が何桁にもわたる	はい	BDF/Radau を使用します
解が滑らかで、妥当な dt になっている	いいえ	陽解法を使い続けます

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

スクリプト	主な出力
scripts/error_norm.py	error_norm、scale_min、scale_max
scripts/adaptive_step_controller.py	accept、dt_next、factor
scripts/integrator_selector.py	recommended、alternatives、notes
scripts/imex_split_planner.py	implicit_terms、explicit_terms、splitting_strategy
scripts/splitting_error_estimator.py	error_estimate、substeps

ワークフロー

1. 硬さを分類する - 固有値の広がりを確認するか、stiffness_detector を使用します
2. 許容誤差を選ぶ - references/tolerance_guidelines.md を参照します
3. 積分器を選択する - scripts/integrator_selector.py を実行します
4. 誤差ノルムを計算する - ステップの採否判定に scripts/error_norm.py を使用します
5. ステップ幅を調整する - scripts/adaptive_step_controller.py を使用します
6. IMEX／分割を計画する - 硬い項と非硬い項が混在する場合は、scripts/imex_split_planner.py を使用します
7. 収束を検証する - より厳しい許容誤差で再実行します

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

ユーザー: 硬いダブルウェルポテンシャルを持つ Allen-Cahn 方程式を解いています。どの積分器を使えばよいですか？

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

1. 積分器の選択肢を確認します。

   python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json
   

2. IMEX 分割を計画します（拡散項は陰的、反応項は陽的）。

   python3 scripts/imex_split_planner.py --stiff-terms diffusion --nonstiff-terms reaction --coupling weak --json
   

3. 推奨：拡散項を陰的、ダブルウェル反応項を陽的に扱う IMEX-BDF2 を使用します。

積分前のチェックリスト

• 硬さと支配的な時間スケールを特定する
• 物理と単位に即した rtol／atol を設定する
• 積分器が硬さに対応していることを確認する
• 誤差ノルムを使って各ステップの採否を判定する
• より厳しい許容誤差で実行し、収束を検証する

CLI の例

# Select integrator for stiff problem with Jacobian
python3 scripts/integrator_selector.py --stiff --jacobian-available --accuracy high --json

# Compute scaled error norm
python3 scripts/error_norm.py --error 0.01,0.02 --solution 1.0,2.0 --rtol 1e-3 --atol 1e-6 --json

# Adaptive step control with PI controller
python3 scripts/adaptive_step_controller.py --dt 1e-2 --error-norm 0.8 --order 4 --controller pi --json

# Plan IMEX splitting
python3 scripts/imex_split_planner.py --stiff-terms diffusion,elastic --nonstiff-terms reaction --coupling strong --json

# Estimate splitting error
python3 scripts/splitting_error_estimator.py --dt 1e-4 --scheme strang --commutator-norm 50 --target-error 1e-6 --json

エラー処理

エラー	原因	解決方法
rtol must be a non-negative finite number / atol must be a non-negative finite number	許容誤差が無効です	0 以上の有限値を使用します
error_norm must be finite and non-negative	誤差ノルムが負または有限値ではありません	誤差の計算を確認します
scale must be positive; with min_scale=0 ensure atol>0 or rtol*|y|>0	すべてのスケール値が 0 になっています（例：rtol=0、atol=0、デフォルトの min_scale=0）	atol>0、rtol>0、または --min-scale > 0 に設定します
argument --controller: invalid choice: ... (choose from p, pi)	コントローラーの種類が無効です	p または pi を使用します
Provide at least one stiff or non-stiff term	項のリストが空です	硬い項または非硬い項を指定します

解釈の指針

誤差ノルムの値

誤差ノルム	意味	対応
< 1.0	ステップを採用できます	採用し、必要に応じて dt を増やします
≈ 1.0	許容誤差の境界です	現在の dt で採用します
> 1.0	ステップは不採用です	棄却し、dt を小さくします

コントローラーの選択

コントローラー	CLI 値	特性	最適な用途
P（初等／積分）	p（デフォルト）	シンプルで、多少オーバーシュートします	硬くなく、精度が中程度の問題
PI（比例積分）	pi	滑らかで堅牢です（--prev-error が必要です）	一般的な用途

PID 制御については、参考情報としてのみ references/error_control.md に記載されています。 adaptive_step_controller.py CLI が実装しているのは p コントローラーと pi コントローラーです。

IMEX 戦略

結合	戦略
弱い	単純な演算子分割
中程度	ストラング分割
強い	完全連成 IMEX-RK

検証チェックリスト

• scripts/error_norm.py でスケーリング済みの error_norm（および scale_min／scale_max）を記録し、コンポーネントが誤って atol のみのスケーリングになっていないことを示すため、scale_min > 0 を確認しました。
• scripts/adaptive_step_controller.py に従い、受理された各ステップの error_norm <= accept_threshold（デフォルトは 1.0）を確認しました。accept: false のステップと、その結果の dt_next／factor を記録し、無理にステップを通過させていません。
• PI コントローラーでは --prev-error を指定し、controller_used が pi と報告されることを確認しました（--prev-error を省略した場合に暗黙的に p にフォールバックすることがないようにします）。
• 問題に合った実際の --stiff／--jacobian-available／--accuracy フラグを指定して scripts/integrator_selector.py を実行し、recommended と notes（例：硬い問題で陰解法を使わない場合の「dt を小さくすることを想定」という警告）を記録しました。
• 演算子分割では、scripts/splitting_error_estimator.py の error_estimate、substeps、dt_effective を記録し、正しい --scheme の次数（lie=1、strang=2）を使って、サブステップ後に error_estimate <= target-error となることを確認しました。
• 収束検証（ワークフローのステップ 7）を実行しました。より厳しい rtol／atol で再実行し、単一の許容誤差での実行結果を鵜呑みにせず、解の変化が目標精度を下回ることを確認しました。

よくある落とし穴と誤った合理化

つい選びたくなる近道	それが誤りである理由／対処法
「陰解法／BDF 法を選んだから、どんな dt でも問題ありません。」	無条件の安定性は精度を意味しません。大きな dt では時間誤差も増大します。error_norm が受理しきい値を満たすか確認し、より厳しい許容誤差で収束検証を実行してください（ワークフローのステップ 7）。
「error_norm が 1 未満だったので、このステップも実行全体も正しいです。」	このノルムが保証するのは、選択した rtol／atol のもとでの局所ステップのみです。許容誤差が緩ければ、全ステップが通過しても大域解は誤っている可能性があります。結果を信頼する前に許容誤差を厳しくし、収束を確認してください。
「ステップを滑らかに進めるため PI コントローラーを使います」が、--prev-error を省略する。	--prev-error がないと、スクリプトは暗黙的に P コントローラーへフォールバックします（controller_used: p）。PI の利点は得られません。直前に受理された error_norm を渡し、controller_used: pi を確認してください。
「ここではストラング分割とリービル分割の違いはほとんどありません。」	分割誤差は、次数 1（lie）と次数 2（strang）に応じて commutator_norm * dt^(order+1) でスケーリングされます。交換子がゼロでなければ、各スキームは dt のべきが丸ごと 1 つ異なります。推測せず、実際の --commutator-norm と --target-error を指定して splitting_error_estimator.py を実行してください。
「セレクターが IMEX／RK-Chebyshev を推奨したので、ヤコビアンなしで陽解法を実行します。」	この分岐が選ばれるのは、陰的ソルバーを使わない硬い問題の場合のみで、スクリプトは「dt を小さくすることを想定」と警告します。notes を確認してください。陰的ソルバーが使用可能であれば、ヤコビアン／Jv 積を与え、BDF／Radau を使用してください。
「クラッシュせずに最終時刻まで実行できたので、積分は妥当です。」	完了したことは正しさを意味しません。ステップの受理（error_norm <= threshold）、分割誤差が target-error 以内であること、より厳しい許容誤差での収束を検証してください。保存系の問題では imex_split_planner.py に --conservative を渡し、保存量を確認してください。

セキュリティ

入力の検証

• すべての数値入力（dt、rtol、atol、error_norm、stiffness_ratio、commutator_norm など）は、関数の境界で有限数であることを検証します
• imex_split_planner.py は、項名を [a-zA-Z_][a-zA-Z0-9_ -]* と長さ・個数の上限に照らして検証し、ユーザーが指定した項のリストにインジェクションペイロードが含まれるのを防ぎます
• カンマ区切りの値リストは、リソースの枯渇を防ぐため、エントリー数を 100,000 件までに制限します
• 数値の上限を適用します。dimension は 10 billion、order は 20、stiffness_ratio は 1e30 を上限とします
• --controller は固定の許可リスト（p、pi）に照らして検証します
• --scheme は既知の分割スキーム（lie、strang）に照らして検証します

ファイルアクセス

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

ツールの制限

• Read：スクリプトのソース、リファレンス、ユーザー設定ファイルの確認に使用します
• Write：積分器の推奨事項や分割計画の保存に使用します。書き込み先はユーザーの作業ディレクトリ内に制限されます
• Grep/Glob：関連ファイルの特定やリファレンスの検索に使用します
• このスキルの allowed-tools では Bash を除外し、ユーザー提供の入力を処理する際にエージェントが任意のコマンドを実行できないようにしています

安全対策

• eval()、exec()、動的なコード生成は使用しません
• すべてのサブプロセス呼び出しでは、明示的な引数リストを使用します（shell=True は使用しません）
• ツールの範囲を縮小し（Bash を除外）、エージェントの操作を読み取り／書き込みのみに制限します
• 項名は使用前にサニタイズし、シェルのメタ文字のインジェクションを防ぎます

制限事項

• スティフネスの自動検出には対応していません：numerical-stability の stiffness_detector を使用してください
• 分割では分離可能であることを前提とします：各項を明確に分離できる必要があります
• ヤコビアンが必要です：一部の手法では、解析的または数値的なヤコビアンが必要です

リファレンス

• references/method_catalog.md - 積分器の選択肢と特性
• references/tolerance_guidelines.md - rtol/atol の選び方
• references/error_control.md - 誤差ノルムと適応の公式
• references/imex_guidelines.md - スティッフ／非スティッフ分割
• references/splitting_catalog.md - 演算子分割のパターン
• references/multiphase_field_patterns.md - フェーズフィールド固有の分割

バージョン履歴

• v1.2.2 (2026-06-24)：検証チェックリストと、刻み幅の採用、PI コントローラーの使用、積分器の選択、分割誤差のチェックをスクリプトの実際の出力に基づいて説明する「よくある落とし穴と合理化」のセクションを追加
• v1.2.0 (2026-06-23)：PI コントローラーの係数と符号を標準形式に修正し、error_norm のスケール崩壊によるクラッシュを修正。スクリプトに合わせてエラーメッセージとコントローラーのドキュメントを修正
• v1.1.0 (2024-12-24)：ドキュメント、判断のガイダンス、例を強化
• v1.0.0：5 つの積分スクリプトを含む初回リリース