differentiation-schemes

微分スキーム

目標

シミュレーションの離散化に向けて、微分スキームを選択し、ステンシルを生成し、精度を評価するための信頼性の高いワークフローを提供します。

要件

• Python 3.10+
• NumPy（ステンシル計算用）
• 重い依存関係なし

収集する入力

入力	説明	例
微分の次数	1階、2階など	1 または 2
目標精度	打ち切り誤差の次数	2 または 4
格子の種類	一様、不均一	uniform
境界の種類	周期、ディリクレ、ノイマン	periodic
滑らかさ	滑らか、または不連続	smooth

選択の指針

スキーム選択フローチャート

Is the field smooth?
├── YES → Is domain periodic?
│   ├── YES → Use central differences or spectral
│   └── NO → Use central interior + one-sided at boundaries
└── NO → Are there shocks/discontinuities?
    ├── YES → Use upwind, TVD, or WENO
    └── NO → Use central with limiters

クイックリファレンス

状況	推奨スキーム
滑らか、周期境界	中心差分、スペクトル法
滑らか、有界領域	中心差分 + 片側境界条件
移流が支配的	風上差分
衝撃波／フロント	TVD、WENO
高精度が必要	コンパクト差分（パデ）、スペクトル法

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

スクリプト	主な出力
scripts/stencil_generator.py	offsets、coefficients、order、accuracy、scheme
scripts/scheme_selector.py	recommended、alternatives、notes
scripts/truncation_error.py	error_scale、order、reduction_if_halved

ワークフロー

1. 要件を特定する - 微分の次数、精度、滑らかさ
2. スキームを選択する - scripts/scheme_selector.py を実行します
3. ステンシルを生成する - scripts/stencil_generator.py を実行します
4. 誤差を推定する - scripts/truncation_error.py を実行します
5. 検証する - 製造解または格子細分化を使ってテストします

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

ユーザー: 一様格子上の拡散方程式で、2階微分を離散化したいです。4次精度を希望します。

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

1. 適切なスキームを選択します（境界の種類が指定されていません。有界領域で周期境界ではない場合は、片側差分／ゴーストセルに関する指針を表示するために --boundary を追加するか、ユーザーに確認します）:

   python3 scripts/scheme_selector.py --smooth --order 2 --accuracy 4 --json
   

2. ステンシルを生成します:

   python3 scripts/stencil_generator.py --order 2 --accuracy 4 --scheme central --json
   

3. 結果: 5点ステンシル、係数は [-1/12, 4/3, -5/2, 4/3, -1/12] / dx² です。

離散化前のチェックリスト

• 微分の次数と目標精度を確認する
• 滑らかさと境界に適したスキームを選択する
• 境界でのステンシルを生成して確認する
• 物理スケールと比較して打ち切り誤差を推定する
• 格子細分化試験で検証する

CLI の例

# Select scheme for smooth periodic problem
python3 scripts/scheme_selector.py --smooth --periodic --order 1 --accuracy 4 --json

# Generate central difference stencil for first derivative
python3 scripts/stencil_generator.py --order 1 --accuracy 2 --scheme central --json

# Generate 4th-order second derivative stencil
python3 scripts/stencil_generator.py --order 2 --accuracy 4 --scheme central --json

# Estimate truncation error
python3 scripts/truncation_error.py --dx 0.01 --accuracy 2 --scale 1.0 --json

エラー処理

エラー	原因	解決方法
order must be positive	微分の次数が無効です	1、2、3、...（最大 6）を指定します
order must be <= 6	微分の次数が大きすぎます	1～6 を指定します
accuracy must be even for central	中心差分に奇数精度が指定されました	2、4、6、... を指定します
scheme must be central, forward, or backward	--scheme の値が無効です	central、forward、または backward を指定します

解釈の指針

ステンシルの特性

特性	意味
対称なオフセット	中心差分（方向性の偏りなし）
非対称なオフセット	片側差分または風上差分
点数が多い	精度は高くなりますが、ステンシルの幅も広くなります

打ち切り誤差のスケーリング

精度の次数	誤差のスケーリング	細分化係数
2次	O(dx²)	2倍の細分化 → 誤差が4分の1
4次	O(dx⁴)	2倍の細分化 → 誤差が16分の1
6次	O(dx⁶)	2倍の細分化 → 誤差が64分の1

一般的なステンシル

微分	精度	点数	係数（× 1/dx または 1/dx²）
1階	2	3	[-1/2, 0, 1/2]
1階	4	5	[1/12, -2/3, 0, 2/3, -1/12]
2階	2	3	[1, -2, 1]
2階	4	5	[-1/12, 4/3, -5/2, 4/3, -1/12]

検証チェックリスト

生成されたステンシルを信頼したり、スキームの推奨を採用したりする前に、以下の各項目について具体的な証拠を記録してください。

• stencil_generator.py --json を実行し、results.accuracy が要求した次数と一致すること、および len(results.offsets) が想定されるステンシル幅（例：4 次精度の中心差分による 2 階微分では 5 点）と等しいことを確認しました。また、central スキームでは、オフセットが 0 を中心に対称であることも確認しました。
• references/stencil_catalog.md を参照して、返された coefficients の妥当性を確認しました。合計が約 0（整合性：演算子が定数を消去する）であること、および少なくとも 1 つの標準ケース（例：2 次精度の d²/dx² では [1, -2, 1]/dx²）で、カタログにあるステンシルが再現されることを確認しました。
• central スキームでは、--accuracy が偶数であることを確認しました（奇数を指定すると accuracy must be even for central により終了コード 2 で終了します）。要求した次数が達成されたと思い込まず、実際の終了コードを記録しました。
• truncation_error.py の error_scale、order、reduction_if_halved を記録し、reduction_if_halved == 2**accuracy であることを確認しました。さらに、references/error_guidance.md にある最小の物理的特徴サイズ（dx/L_feature）と error_scale を比較し、グリッドが物理現象を実際に解像できていることを確認しました。
• 独立した格子細分化または解析解を用いた研究を 3 つ以上の格子で実行しました（スクリプト自体にはこの機能はありません）。次数を提示する前に、観測次数 p_obs = log(e_h/e_{h/2})/log(2) が形式上の accuracy の約 10% 以内であることを確認しました。
• 有界（非周期）領域では、境界ステンシルを references/boundary_handling.md に従って明示的に生成または選択（--scheme forward|backward または --boundary の指針）したことを確認しました。内部ステンシルだけでは境界でのスキーム次数が定義されないためです。
• 非滑らかな場（衝撃波／フロント）では、scheme_selector.py が高次中心差分を推奨しておらず、代わりにリミッター／WENO／風上差分の手法が選択されていることを確認しました。

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

つい選びたくなる近道	誤りである理由／すべきこと
「ステンシル生成ツールが係数を返したのだから、このスキームは指定した次数になっている。」	accuracy フィールドは要求をそのまま表示しているだけで、実測値ではありません。格子細分化による検証で達成次数を確認し、係数が既知のステンシルと一致して合計が約 0 になることを確かめてください。
「--accuracy 3 で中心スキームの 4 次精度を指定したけれど、自動的に切り上げてくれるだろう。」	切り上げられません。中心スキームで奇数の精度を指定すると accuracy must be even for central で拒否され、終了コードは 2 です。偶数の精度を指定してください。奇数の指定はエラーであり、通知なしに引き上げられることはありません。
「ここでは精度次数を上げれば、必ず誤差が小さくなる。」	truncation_error.py が報告するのは漸近的なスケーリング（scale * dx**accuracy）です。粗い格子や解像度が不足した特徴では、高次の項が支配的になるとは限りません。また、非常に細かい格子では丸め誤差（O(ε/dx^p)）が優勢になることがあります。error_scale を特徴のサイズと比較し、単調に改善すると決めつけないでください。
「2 つの格子でよく一致しているから、収束している。」	2 つの格子では、観測次数を推定したり、漸近領域にあることを確認したりできません。形式次数を主張する前に、3 つ以上の格子を使って p_obs を計算してください（references/error_guidance.md を参照）。
「内部ステンシルが 4 次精度だから、計算全体も 4 次精度だ。」	生成ツールが出力するのは内部ステンシルだけです。境界の閉包処理によって、全体の精度が制限されることがよくあります。片側／ゴーストセルのステンシルを明示的に生成し、境界によって観測次数が低下しないことを確認してください（references/boundary_handling.md を参照）。
「場に衝撃波があるけれど、幅広い中心ステンシルのほうが高精度なので、これを使おう。」	高次の中心有限差分法は、不連続点で振動（ギブス現象）を起こします。scheme_selector.py は --discontinuous に対してリミッター／WENO を使う有限体積法（FV）または風上差分法を推奨します。形式次数を最大化するのではなく、推奨に従ってください。
「--offsets をカスタマイズすれば、好きなステンシルを作れる。」	オフセットは重複不可で、長さは最大 51 に制限されており、微分次数より多く指定する必要があります。満たさない場合、スクリプトは終了コード 2 で終了します。実行が成功しても、意図した精度が保証されるわけではありません。係数と観測次数を確認してください。

セキュリティ

入力の検証

• --order（微分次数）は、上限（order <= 6）付きの正の整数として検証されます
• --accuracy は正の整数（<= 8）として検証され、さらに中心スキームでは偶数である必要があります
• --scheme は、固定の許可リスト（central、forward、backward）に対して検証されます
• --offsets（カスタムステンシル）は長さが最大 51 に制限され、重複のない整数として解析され、微分次数より大きい値である必要があります
• --dx と --scale は有限の非負数として検証されます（--dx は厳密に正である必要があります）
• ユーザーが指定した文字列がコードパスやシェルコマンドに埋め込まれることはありません

ファイルアクセス

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

ツールの制限

• Read：スクリプトのソース、リファレンス、ユーザー設定ファイルの確認に使用します
• Bash：3 つの Python スクリプト（stencil_generator.py、scheme_selector.py、truncation_error.py）を、明示的な引数リストを指定して実行するために使用します
• Write：生成したステンシル係数やスキームの推奨を保存するために使用します。書き込み先はユーザーの作業ディレクトリ内に限定されます
• Grep/Glob：関連ファイルの特定やリファレンスの検索に使用します

安全対策

• eval()、exec()、動的なコード生成は使用しません
• すべてのサブプロセス呼び出しで、明示的な引数リストを使用します（shell=True は使用しません）
• ステンシルの計算では、サイズが小さく上限のある配列のみを使用します（微分次数は 6、精度は 8、カスタムオフセットリストは 51 点が上限です）
• すべての出力は、シェルで解釈可能な内容を含まない決定的な JSON です

制限事項

• 境界の処理：Stencil generator は内部のステンシルを提供します。境界には個別の処理が必要です
• 不均一グリッド：標準的なステンシルは均一な間隔を前提としています
• スペクトル法：Stencil generator の対象外です

参考資料

• references/stencil_catalog.md - 一般的なステンシル
• references/boundary_handling.md - 片側スキーム
• references/scheme_selection.md - FD/FV/スペクトル法の比較
• references/error_guidance.md - 打ち切り誤差のスケーリング

バージョン履歴

• v1.2.2 (2026-06-24)：検証チェックリスト（スクリプトの JSON 出力と参考資料に基づくエビデンスを使用）と、よくある落とし穴とその正当化をまとめた表を追加しました。
• v1.2.0 (2026-06-23)：偶数精度と次数の上限の検証を必須化し、スクリプトに合わせてセキュリティ／エラー処理／出力のドキュメントを修正し、CLI／eval の例を修正し、入力検証を強化しました
• v1.1.0 (2024-12-24)：ドキュメント、選択ガイド、例を拡充しました
• v1.0.0：3 つの微分スクリプトを含む初回リリース