beach-bem 1.3.0

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

BEACH（BEM + Accumulated CHarge）

公開ドキュメント: GitHub Pages

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

v1.0 の主対象は insulator accumulation（絶縁体への電荷蓄積） です。 BEM による電荷堆積とテスト粒子追跡を繰り返すことで、各 batch ごとに表面電位が更新されていきます。

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

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

# シミュレーション実行 → 可視化
beach beach.toml
beachx animate outputs/latest --quantity potential --save-gif potential_history.gif

1. セットアップ

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

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.0 beach.toml を作成・検証する

beachx config を使うと、実行用 beach.toml のひな形作成と高水準記法の展開ができます。 実行前の検査には beachx lint beach.toml を使います。 日常的な編集対象も Fortran 実行系が読むファイルも beach.toml です。

詳しい使い方は次を参照してください。

• docs/config_workflow.md: beachx config と高水準記法の運用ガイド
• docs/fortran_parameter_file.md: beach.toml に残る最終キー仕様

mkdir run_periodic2
cd run_periodic2

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

beachx config init は周期 2 軸 FMM、volume seed の電子・イオン、平面メッシュ、標準出力設定を含む小さな beach.toml を作ります。 サンプルは examples/periodic2_basic/beach.toml にあります。 生成される beach.toml には schemas/beach.schema.json への #:schema ... directive を付けています。

空間座標系まわりは、高水準記法で指定して beachx config render で最終キーへ展開できます。たとえば sim.box_origin + sim.box_size、reservoir_face / photo_raycast の inject_region_mode = "face_fraction"、mesh.templates の placement_mode = "box_anchor"、mesh.groups.* の scale_from = "box_x" は、具体的な box_min / box_max / pos_low / pos_high / center / size_x などへ変換されます。

2.1 推奨: beach コマンド

beach examples/beach.toml

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

2.2 出力確認

ls outputs/latest
beachx inspect outputs/latest

主な出力:

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

2.3 可視化

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

# sim.field_bc_mode = "periodic2" の mesh を周期セルへ寄せて描く場合
beachx inspect outputs/latest \
  --save-mesh outputs/latest/charges_mesh_periodic.png \
  --save-potential-mesh outputs/latest/potential_mesh_periodic.png \
  --apply-periodic2-mesh

# 周期メッシュを n 周期分複製して描く場合（1 なら 3×3 = 9 コピー）
beachx inspect outputs/latest \
  --save-mesh outputs/latest/charges_mesh_tiled.png \
  --periodic2-repeat 1 --apply-periodic2-mesh

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

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

beachx coulomb outputs/latest \
  --component z \
  --save outputs/latest/coulomb_force_z.png

beachx mobility outputs/latest \
  --density-kg-m3 2500 \
  --mu-static 0.4 \
  --save-csv outputs/latest/mobility_summary.csv

# Fortran FMM core と同じ field kernel で object ごとの総電荷・合力・合トルクを出す場合
make build-kernel
beachx kernel-forces outputs/latest \
  --save-csv outputs/latest/object_forces_kernel.csv

beachx coulomb は、beach.toml の mesh.templates が見つかれば object の kind と順序をそこから読み取り、既定では全 object を target 軸に並べて行列を描きます。特定 kind だけに絞りたいときは --target-kinds sphere のように指定できます。 beachx mobility は、既定で plane を support とみなし、それ以外の object について合力・合トルクと lift_ratio / slide_ratio / roll_ratio を CSV に書き出します。質量由来の指標は --density-kg-m3 と beach.toml の幾何情報が必要です。 beachx kernel-forces は libbeach_field_kernel を介して Fortran FMM core を Python から呼び出し、beach.toml の sim.softening / sim.field_bc_mode / periodic2 / tree 設定を使って object ごとの net force を計算します。共有ライブラリは make build-kernel で build/libbeach_field_kernel.so に生成できます。別の場所に置く場合は --library または BEACH_FIELD_KERNEL_LIB を指定します。設定ファイルが出力ディレクトリ近傍にない場合は --config path/to/beach.toml を指定します。

旧 alias の beach-inspect / beach-animate-history / beach-plot-coulomb-force-matrix / beach-plot-potential-slices なども当面は使えますが、今後は beachx ... を推奨します。

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

from beach import Beach

run = Beach("outputs/latest")  # config_path=... で beach.toml を明示指定可能

# 電荷 [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)

# periodic2 mesh を周期セルへ寄せて表示
run.plot_mesh(apply_periodic2_mesh=True)
run.plot_potential(apply_periodic2_mesh=True)

# n 周期分複製して表示（1 なら 3×3 = 9 コピー）
run.plot_mesh(apply_periodic2_mesh=True, periodic2_repeat=1)
run.animate_mesh("charge_tiled.gif", apply_periodic2_mesh=True, periodic2_repeat=1)

# ポテンシャル [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)

# object ごとの Coulomb 力行列（beach.toml があれば plane/sphere などを自動ラベル化）
fig_f, ax_f = run.plot_coulomb_force_matrix(
    component="z",
)
fig_f.savefig("outputs/latest/coulomb_force_z.png", dpi=150)

# 移動可能性の簡易評価（既定では plane 以外を対象）
mobility = run.analyze_coulomb_mobility(
    density_kg_m3=2500.0,
    mu_static=0.4,
)
for record in mobility.records:
    print(record.label, record.lift_ratio, record.slide_ratio, record.roll_ratio)

# Fortran FMM core を共有ライブラリとして呼び、object ごとの総電荷・合力を計算
kernel_records = run.calc_object_forces_kernel()
for record in kernel_records:
    print(record.mesh_id, record.total_charge_C, record.force_N)

# object を一時的に移動・回転した what-if scene で力を再評価
scene = run.scene()
moved = scene.move(2, by=[1.0e-3, 0.0, 0.0]).rotate(
    2,
    axis=[0.0, 0.0, 1.0],
    angle_deg=15.0,
)
records = moved.calc_object_forces_kernel(target_mesh_ids=[2])
print(records[0].force_N, records[0].torque_Nm)

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

3.1 負荷見積もり

beachx 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 check
make run CONFIG=examples/beach.toml

開発中の標準確認は make check です。BEACH_VERSION_MODE=dev を使って Fortran 側へ渡す version 文字列を 1.2.0-dev のように固定するため、git hash が変わっても fpm の compile-flag hash が変わらず、差分コンパイルを再利用できます。

make build と make install は既定で git hash 付き version を埋め込みます。必要なら明示指定できます。

make build VERSION_MODE=dev       # 開発中の差分コンパイル優先
make build VERSION_MODE=plain     # fpm.toml の version だけを埋め込む
make build VERSION_MODE=git       # git describe 付き（既定）

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

make install-generic
make install-camphor

4.3 fpm 直接実行（低レベル確認向け）

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

通常の開発では build.sh 経由の make run / make check を優先してください。 build.sh が __BEACH_VERSION__ と __BEACH_VERSION_MODE__ を安定した形で渡します。

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 テスト

make test-l0      # L0: static/schema/build check
make test         # L1: normal development loop
make test-l2      # L2: contract/integration
make test-l3      # L3: heavy/release gate
make test-heavy   # heavy Fortran targets only
make test-full    # unfiltered fpm test

make test は L1 の alias で、Python tests と軽量 Fortran target を実行します。 FMM 系の長時間 target は通常の開発ループから外し、make test-l3 / make test-heavy / make test-fortran-heavy / make test-full で明示実行します。個別 target だけ確認する場合は次を使います。

FPM_ACTION=test ./build.sh --target test_version

KUDPC のログインノードでは make test* / fpm test を直接実行せず、tssrun または sbatch ジョブ内の計算ノードで実行してください。

4.5 Fortran 整形

Fortran の *.f90 / *.F90 は fprettify -i 2 を標準 formatter とします。 生成バックアップの *.i90 は整形対象外です。

ローカルで hook を有効にするには:

python -m pip install pre-commit
make install-hooks

手動整形と CI 相当の確認:

make fmt-fortran
make fmt-check-fortran

GitHub Actions でも同じ pre-commit 設定を --all-files で実行し、整形漏れを検知します。

4.6 Fortran ドキュメント生成

GitHub Pages 向けの Fortran ドキュメントは FORD で生成します。 モジュール API、use 依存グラフ、docs/ 配下の運用ドキュメントをまとめて公開できます。

python -m pip install -r docs/requirements.txt
# Ubuntu / Debian 系
sudo apt-get install -y graphviz

make docs-fortran

出力先は build/ford-docs/ です。 main への push では GitHub Actions の Fortran Docs workflow が同じ手順で GitHub Pages を更新します。

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
• beach.toml JSON Schema: schemas/beach.schema.json
• Coulomb FMM コア仕様: docs/fortran_fmm_core.md
• 自動生成の依存関係マップ: make docs-fortran 実行後の docs/fortran_dependency_map.md
• 実装仕様（source of truth）: SPEC.md
• 設定サンプル: examples/beach.toml