BEACH（BEM + Accumulated CHarge）

BEACH は、境界要素法（BEM）による表面電場計算と テスト粒子追跡を組み合わせた表面帯電シミュレータです。

• beach: Fortran 製のシミュレーション実行バイナリ
• beachx: 設定検査、可視化、ワークロード見積もりなどの Python CLI
• beach/: Fortran 出力を読むための Python ライブラリ

現行の主対象は 絶縁体表面への電荷蓄積（insulator accumulation） です。 各 batch で電場計算、Boris pusher による粒子前進、メッシュ衝突判定、表面への電荷堆積を行い、表面電位の時間発展を出力します。

電子ビーム照射下での絶縁体メッシュ上の電位分布の時間発展

_{3D model: Rubber Duck PBR Game Ready (TurboSquid)}

必要なもの

Python パッケージのインストール時に Fortran 実行バイナリもビルドします。通常の pip installではfpmも隔離build環境へ自動導入されるため、事前に必要なのはmakeと Fortran compilerです。

make --version
gfortran --version
python --version

gfortran 以外の Fortran compiler を使う場合は、環境に合わせて FC / FPM_FC などを設定してください。

クイックスタート

通常利用では PyPI から導入します。

python -m pip install -U pip setuptools wheel
python -m pip install beach-bem

ユーザーインストール時に beach / beachx が見つからない場合は PATH を確認してください。

export PATH="$HOME/.local/bin:$PATH"

小さな設定を作って実行します。

mkdir run_periodic2
cd run_periodic2

beachx config init
beachx lint beach.toml
beach beach.toml

結果は既定で outputs/latest/ に出力されます。

beachx inspect outputs/latest
beachx animate outputs/latest --quantity potential --save-gif potential_history.gif

開発版を直接試す場合:

python -m pip install "git+https://github.com/Nkzono99/BEACH.git"

設定ファイル

実行時にbeachが読むのはbeach.tomlです。box_origin / box_size、inject_region_mode = "face_fraction"、 placement_mode、mesh.groupsなどの座標・配置パラメータもFortran側で直接解決されます。 まずは beachx config init が生成したファイルを編集し、実行前に beachx lint beach.toml で検査してください。

詳細:

• 設定作成・検証: 設定を編集する
• beach.toml 仕様: Fortran パラメータファイル仕様
• 実行・開発・テスト: Fortran 中心ワークフロー

よく使うコマンド

旧 CLI 名（beach-inspect、beach-animate-history、beach-estimate-workload など）は互換用 alias です。新しい利用者には beachx ... を推奨します。

ドキュメント

利用者向け・開発者向けドキュメントは GitHub Pages に集約しています。

• 日本語: BEACH ドキュメント
• English: BEACH Documentation
• Fortran API: GitHub Pages / fortran（FORD）
• 入門: インストール / 10分チュートリアル / 出力の読み方
• 運用: 設定レシピ / 計算結果の妥当性確認 / トラブルシューティング
• アルゴリズム: 概要 / 場ソルバー / 粒子更新 / FMM / batch_duration 安定性
• Python 後処理 API / CLI: Python 後処理 API リファレンス

Pages ビルド:

• make docs-deps: Starlight 依存を npm ci でインストール
• make docs-starlight: Starlight 本体のみを生成
• make docs-pages: Starlight 本体と FORD サブサイトを build/starlight-site/ に生成

リポジトリ構成

• src/, app/: Fortran 本体
• beach/: Python 後処理ライブラリと beachx
• docs-site/: GitHub Pages 用 Starlight サイト
• examples/: 設定例・補助スクリプト
• tests/fortran/, tests/python/: テスト
• docs/: 利用者・開発者向けドキュメント
• schemas/, beach/config/schemas/: beach.toml JSON Schema

開発者向け

ローカル checkout を編集する場合:

python -m pip install fpm
python -m pip install -e . --no-build-isolation
make check

--no-build-isolationやmakeを直接使う開発では、fpmをPATH上へ用意してください。

Python 側の確認:

pytest -q
ruff check .

Fortran を含むテストは時間がかかるため、目的に応じて tiered target を選んでください。

make test-l0
make test-l1
make test-l2
make test-l3

KUDPC のログインノードでは make test* / fpm test / 長時間の Fortran 実行を直接走らせず、計算ノードへ投入してください。詳細は Fortran 中心ワークフロー を参照してください。