beach-bem 0.6.5

BEACH (BEM + Accumulated CHarge): BEM surface-charging + test-particle prototype (insulator mode) with hybrid E-field and Boris pusher.

BEACH（BEM + Accumulated CHarge）

BEACH は、BEM（境界要素法）ベースの表面帯電 + テスト粒子追跡シミュレータです。
計算本体は Fortran（fpm 管理）、Python は後処理・可視化を担当します。

v0.x の主対象は insulator accumulation（絶縁体への電荷蓄積） です。

推奨ワークフロー

通常利用では、pip install beach-bem で導入して beach を実行する運用を推奨します。
pip install -e や make は、開発に参加する場合の手順として扱います。

1. 利用者向けセットアップ

1.1 前提ツール

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

1.2 PyPI から一括インストール（推奨）

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

開発版を直接試したい場合は、Git URL からも導入できます。

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

このインストールでは、ビルド時に make install が実行され、Python 側と Fortran 実行バイナリ（beach）が同時に導入されます。 ユーザーインストール時は ~/.local/bin に入るため、必要なら PATH を追加してください。 pip 経由のビルドでは既定で INSTALL_PROFILE=auto を使います。必要なら INSTALL_PROFILE=camphor などを環境変数で上書きできます。 auto 失敗時は既定で generic へフォールバックします。無効化したい場合は BEACH_PIP_FALLBACK_GENERIC=0 を指定してください。

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

2. 実行

2.1 推奨: beach コマンド

beach examples/beach.toml

引数なしの場合は、カレントディレクトリの beach.toml を自動読込します。

2.2 出力確認

ls outputs/latest
beach-inspect outputs/latest

主な出力:

• summary.txt
• charges.csv
• mesh_triangles.csv
• charge_history.csv（history_stride > 0 のとき）

2.3 可視化

beach-inspect outputs/latest \
  --save-bar outputs/latest/charges_bar.png \
  --save-mesh outputs/latest/charges_mesh.png

beach-animate-history outputs/latest \
  --quantity charge \
  --save-gif outputs/latest/charge_history.gif \
  --total-frames 200

beach-plot-potential-slices outputs/latest \
  --grid-n 200 \
  --vmin -20 --vmax 20 \
  --save outputs/latest/potential_slices.png

Python から mesh source ごとの面積重み付き箱ひげ図を作る例:

from beach import Beach

run = Beach("outputs/latest")

# 電荷 [C] の面積重み付き箱ひげ図（mesh sourceごと）
fig_q, ax_q = run.plot_mesh_source_boxplot(
    quantity="charge",
    step=-1,          # 最新 history。None なら charges.csv を使う
    showfliers=False,
)
fig_q.savefig("outputs/latest/charge_box_by_source.png", dpi=150)

# ポテンシャル [V] の面積重み付き箱ひげ図（mesh sourceごと）
fig_phi, ax_phi = run.plot_mesh_source_boxplot(
    quantity="potential",
    softening=0.0,
    self_term="area_equivalent",
)
fig_phi.savefig("outputs/latest/potential_box_by_source.png", dpi=150)

3. 運用でよく使うコマンド

3.1 負荷見積もり

beach-estimate-workload examples/beach.toml --threads 8

3.2 再開実行

[output]
dir = "outputs/latest"
resume = true

同じ output.dir で beach を再実行すると続きから計算します。

4. 開発に携わる場合

ローカル開発では、Python と Fortran を分けて運用するのが便利です。

4.1 Python 側（編集可能インストール）

python -m pip install -U pip setuptools wheel
python -m pip install -e . --no-build-isolation

4.2 Fortran 実行系（make）

make

make のデフォルトターゲットは install で、BUILD_PROFILE=auto（ホスト自動判定）を使います。 必要に応じて明示指定できます。

make install-generic
make install-camphor

4.3 fpm 直接実行（開発向け）

fpm run --profile release --flag "-fopenmp" -- examples/beach.toml

MPI + OpenMP（USE_MPI 有効化）:

FPM_FC=mpiifort \
fpm run --profile release --flag "-fpp -DUSE_MPI -qopenmp" \
  --runner "mpirun -n 4" -- examples/beach.toml

4.4 テスト

pytest -q
fpm test

5. プロジェクト構成

• src/, app/: Fortran 本体
• tests/fortran/: Fortran テスト
• beach/: Python 後処理ライブラリ
• tests/python/: Python テスト
• examples/: 設定例・補助スクリプト
• docs/: 運用ドキュメント
• SPEC.md: 現行 Fortran 実装仕様

6. ドキュメント案内

• Fortran 実行フロー: docs/fortran_workflow.md
• beach.toml 仕様: docs/fortran_parameter_file.md
• Coulomb FMM コア仕様: docs/fortran_fmm_core.md
• 実装仕様（source of truth）: SPEC.md
• 設定サンプル: examples/beach.toml