FMMを使う

このページは、BEACH の利用者が FMM を選び、計算領域を設定し、Direct との誤差と実行時間を確認するための 利用手順です。FMM は、多数の三角形要素が作る遠方場を近似して、同じ mesh 上で多数の粒子位置を評価する計算を 高速化します。小規模計算では固定費が上回るため、Direct との精度比較と実測時間の両方で採用を決めてください。

読了後は、free-space FMM の最小設定、精度調整、Direct 比較、性能測定を一つのケースで実行できます。 展開式、内部データ構造、更新アルゴリズム、並列実装は Coulomb FMMコア内部実装を正本とします。

上端 H 近傍の局所展開誤差は、上部真空の Fourier 切替で回避できます。 fields.periodic.upper_fourier.switch_height="auto" は上部真空の非零成分を Fourier 評価へ切り替えます。

FMMを選ぶか判断する

遠方の寄与は木を通して局所展開へ渡し、近傍の三角形積分と合わせて評価します。

条件	選択
要素数が多く、1 batch で多数の粒子 step を評価する	FMM を候補にし、release build で Direct と実測比較する
無限 2 軸周期場を本番計算で使う	FMM と cached_kneq0 を使う
小規模ケース、基準解、近似誤差の確認	Direct を使う
free-space で要素数による自動選択を使いたい	fields.solver.method="auto" を使い、解決された solver を出力で確認する

FMM の有利・不利は要素数だけでなく、粒子数、追跡 step 数、評価点の分布にも依存します。 Treecode を含む solver 全体の選択は場の評価を参照してください。

最小設定で自由空間FMMを使う

既に lint が通るケースの [fields.solver]、[domain]、[fields]、[output] を次のように設定します。 box の値は例なので、実際の計算領域を使ってください。

[fields.solver]
method = "fmm"

[domain]
box_min = [-0.5, -0.5, -0.1]
box_max = [ 0.5,  0.5,  1.0]
periodic_axes = []

[fields]
boundary = "free"

[output]
enabled = true
dir = "outputs/fmm"

完全なケースは examples/panel_fmm.toml にあります。この example は 短い確認用に output.enabled=false なので、結果を調べる場合は上の [output] 設定へ変更してください。 入力検査、実行、solver の確認を順に行います。

beachx lint beach.toml
beach beach.toml
beachx inspect outputs/fmm
grep '^field_reconstruction_resolved_field_solver=' outputs/fmm/summary.txt

lint の末尾が status=ok、実行の終了コードが 0 になり、最後のコマンドが field_reconstruction_resolved_field_solver=fmm を表示すれば FMM 経路で完了しています。 これは実行完了の確認であり、近似誤差や物理的妥当性の合格判定ではありません。

domainで評価範囲を覆う

[domain] は粒子領域だけでなく、FMM が高速評価する target tree の範囲も定めます。 粒子が到達し得る位置をすべて box 内に入れてください。要素中心の電位や履歴を評価する場合は、mesh も box 内に収めると範囲外評価を避けられます。

box は box_min と box_max、または box_origin と正の box_size のどちらか一組で指定します。 free 場で範囲外の点を評価すると、BEACH は全要素の Direct 和へ fallback します。結果は得られますが、頻発すると FMM の速度上の利点が失われます。cached_kneq0 を使う periodic2 計算では範囲外 target を受理しません。

cached_kneq0 の遠方演算子は box の固定格子を使い、同じ box と設定なら物体集合が違っても再利用できます。 保存先は fields.periodic.cache_dir の明示指定を優先し、省略時は $BEACH_CACHE_DIR/periodic2、 $XDG_CACHE_HOME/beach/periodic2、$HOME/.cache/beach/periodic2 の順で決めます。 メッシュの殻への収容条件と事前生成は periodic2 遠方補正を参照してください。

精度を調整する

最初は fields.solver.tree.theta と fields.solver.tree.leaf_max を省略し、要素数から解決される値を基準にします。 この自動調整は、明示的に fields.solver.method="fmm" を選んだ場合にも適用されます。解決値は次で確認できます。

grep -E '^field_reconstruction_(tree_theta|tree_leaf_max|fmm_expansion_order)=' \
  outputs/fmm/summary.txt

設定	調整時の見方
fields.solver.tree.theta	小さくすると遠方近似の採用条件が厳しくなり、一般に高精度・低速になる。0 < theta <= 1
fields.solver.tree.leaf_max	木の深さと近傍 Direct 計算量のバランスを変える。1 以上で複数値を比較する
fields.solver.normalization	内部座標の数値スケールだけを変える。物理単位や FMM 近似の合格条件には使わない

現行 simulator の展開次数は 4 固定で、入力から変更できません。次の順で調整します。

1. 自動解決値で基準実行する。
2. fields.solver.tree.theta を小さくした実行を追加する。
3. fields.solver.tree.leaf_max も変え、目的の観測量が安定する範囲を探す。
4. Direct との差が許容範囲内で、かつ実測時間が短い組合せを採用する。

要素数別の自動解決値と全キーの型・既定値は入力パラメータを参照してください。

Directと比較して精度を確認する

Direct と FMM は、どちらも要素電荷を同じ triangle P0 source として扱います。そのため、同じ mesh での差は 主に FMM の近似誤差を表します。mesh 離散化誤差は、別に mesh を細分化して確認してください。

自由空間の縮小ケースを複製し、solver と出力先だけを分けます。最初の solver 誤差比較では run.batch_count=1 とし、初期表面電荷が同じ状態から得た要素電荷を使います。

設定ファイル	fields.solver.method	output.dir
direct.toml	"direct"	"outputs/direct"
fmm.toml	"fmm"	"outputs/fmm"

mesh、粒子、乱数 seed、thread 数、particles.tracking.dt_s、fields.solver.normalization、出力条件は一致させます。

beachx lint direct.toml
beachx lint fmm.toml
OMP_NUM_THREADS=1 beach direct.toml
OMP_NUM_THREADS=1 beach fmm.toml
beachx inspect outputs/direct
beachx inspect outputs/fmm

同じ評価点での電場と電位は、電位と電場の Python APIで比較できます。 基準場がほぼ 0 の点では相対誤差が不安定になるため、絶対誤差または代表場で正規化した誤差も使ってください。 solver 誤差が合格した後に代表的な複数 batch へ延長し、吸収・escape 数、要素別の最終電荷、 charge_ledger.csv も比較します。許容値は研究目的に応じて先に決め、 計算結果の妥当性確認に従って判定します。

panel 面上ちょうどの電場は FMM と Direct で trace の規約が異なるため、通常の点ごとの一致判定に使いません。 periodic2 の Direct 基準は solver 名だけを変更して作れません。 periodic2 静電場の split reference を使用してください。

性能を測る

精度条件を満たした後、release build と実運用に近い粒子数で測定します。Direct と FMM で MPI rank、OpenMP thread、 mesh、粒子、出力条件を揃え、ローカル環境または計算ノードの割当内で実行してください。

BEACH_PROFILE=1 OMP_NUM_THREADS=8 beach direct.toml
BEACH_PROFILE=1 OMP_NUM_THREADS=8 beach fmm.toml
beachx profile outputs/direct/performance_profile.csv \
  --save outputs/direct/performance_profile.png
beachx profile outputs/fmm/performance_profile.csv \
  --save outputs/fmm/performance_profile.png

全体比較には simulation_total 行の rank_max_s を使います。FMM の固定費は field_solver_init、 batch ごとの場更新は field_refresh、粒子評価を含む追跡は particle_batch で確認できます。 小ケースでは初期化の固定費が Direct を上回る場合があります。

output.history.potential などの出力条件も計算量を変えるため、比較間で一致させます。periodic2 の cached_kneq0 は cold cache と warm cache を分けて測定してください。計測項目の定義は 実行時の性能計測を参照してください。

periodic2でFMMを使う

periodic2 の通常の本番経路は FMM です。無限周期の非零 mode には cached_kneq0 を使い、 物理的 zero mode を fields.periodic.lower_boundary_model で明示します。fields.periodic.backend="finite_images" は 有限画像近似であり、無限周期解ではありません。

完全な構成は examples/cached_periodic.tomlを参照してください。 成分の選択と検証はperiodic2 静電場、cache の生成と再利用は periodic2 遠方補正を正本とします。

遠方演算子の cache を別 job で先に作る

cached_kneq0 は、初めての box・展開次数・Ewald 設定で走るとき、初期化中に遠方演算子を作ります。 三層レゴリス規模では数十コアで数分、数コアでは 30 分以上かかり、その間は最初の batch が始まりません。 本番 job の時間枠と rank 数（checkpoint 再開で固定される）を cache 作りに使わないよう、次の順で運用します。

1. cache の置き場所を計算ノードから見える共有ファイルシステムにし、全 job で同じ場所を使う。 export BEACH_CACHE_DIR=/path/to/shared/beach-cache（または fields.periodic.cache_dir）。
2. 本番より多い MPI rank の短い job で beach --prepare-periodic-cache beach.toml を実行する。 生成は相対オフセットの類ごとに rank へ分配され、各 rank は OpenMP で並列化される。
3. 本番 job はその job の完了後に投入する（Slurm なら --dependency=afterok:<cache job>）。 本番の summary.txt で periodic2_cache_hit=T と periodic2_operator_build_count=0 を確認する。

演算子は要素を含むセルの分だけ作られ、同じ box で物体集合を変えると足りないセルが追加されます。 物体集合を変える sweep では、本番の前にすべての物体集合について --prepare-periodic-cache を 1 つの job で順に流してください。 同じ cache へ同時に生成すると lock で 1 つずつ実行されるため、本番 job を並べて投げても速くならず、待つ job の時間枠を消費します。 cache ファイルは数百 MB になることがあります（三層レゴリスの全セルで約 300 MB）。

現行制約を確認する

• FMM が扱う source は Coulomb の triangle P0 要素で、別の kernel は選べない。
• simulator の展開次数は 4 固定で、次数収束は入力から実行できない。
• 対応する場境界は free と periodic2。完全な互換表は場の評価に従う。
• mesh geometry は実行中に固定される。電荷だけが batch ごとに更新される。
• fields.solver.normalization を変更しても、出力される電場と電位は SI 単位へ戻される。
• FMM 自体は外部 plasma / sheath を解かない。外部シース closure の電位基準は FMM の外側で周期 k=0 成分へ与える。

FMM の数式、内部 API、geometry と電荷状態の分離、範囲外 fallback、OpenMP 実装を調べる開発者は Coulomb FMMコア内部実装へ進んでください。