Python 後処理 API リファレンス

BEACH の Python パッケージ (beach) は、Fortran シミュレーション結果の読み込み・解析・可視化を担う後処理レイヤです。 Fortran 実行系が出力するファイル群（summary.txt, charges.csv, mesh_triangles.csv 等）を読み込み、電位再構成、Coulomb 力計算、電場計算、電気力線追跡、3D 可視化を Python 側で行います。

1. パッケージ構成

すべての公開シンボルは beach トップレベルおよび beach.fortran_results からインポートできます。

from beach import Beach, calc_coulomb, compute_electric_field_points, trace_field_lines

2. Beach ファサードクラス

出力ディレクトリを 1 つ束ねて、主要な解析・可視化メソッドを提供する高水準インターフェースです。

b = Beach("outputs/latest")

2.1 コンストラクタ

2.2 プロパティ

2.3 メソッド一覧

3. 結果読み込み

3.1 load_fortran_result(directory)

Fortran 出力ディレクトリを読み込み、FortranRunResult を返します。

from beach import load_fortran_result

result = load_fortran_result("outputs/latest")
print(f"要素数: {result.mesh_nelem}, バッチ数: {result.batches}")
print(f"吸収: {result.absorbed}, 脱出: {result.escaped}")

必須ファイル: summary.txt, charges.csv オプションファイル: mesh_triangles.csv, mesh_sources.csv, charge_history.csv, mesh_potential.csv

3.2 FortranRunResult 型

4. 電位再構成

4.1 compute_potential_mesh(result, *, softening, self_term, periodic2, reference_point)

三角形重心での電位を再構成します。Fortran が mesh_potential.csv を出力済みで条件が一致する場合はそちらを優先します。

戻り値: ndarray (mesh_nelem,) [V]

4.2 compute_potential_points(result, points, *, softening, chunk_size, periodic2, reference_point)

任意 3D 点での電位を計算します。

戻り値: ndarray (n_points,) [V]

4.3 compute_potential_slices(result, *, box_min, box_max, grid_n, xy_z, yz_x, xz_y, ...)

XY/YZ/XZ 平面上の電位断面を計算します。

戻り値: dict[str, PotentialSlice2D] (キー: "xy", "yz", "xz")

5. Coulomb 力/トルク計算

5.1 calc_coulomb(result, target, source, *, step, softening, torque_origin, periodic2)

target メッシュグループが source から受ける Coulomb 力とトルクを計算します。

戻り値: CoulombInteraction

periodic2 パラメータによる周期クーロン和

periodic2 が指定された場合、ソース電荷の画像シェル ix in [-nimg, nimg], iy in [-nimg, nimg] を 2 軸周期方向に生成し、最近接セル和としてクーロン力/トルクを計算します。

periodic2=None（デフォルト）の場合は、出力ディレクトリ近傍の beach.toml を探索し、sim.field_bc_mode="periodic2" が設定されていれば自動的に周期設定を適用します。これは compute_potential_mesh 等の他の関数と同じ自動判定ロジックです。

5.2 CoulombInteraction 型

使用例

from beach import Beach

b = Beach("outputs/latest")

# mesh_id=0 が mesh_id=1 から受ける Coulomb 力
interaction = b.calc_coulomb(target=0, source=1)
print(f"Force on target: {interaction.force_on_a_N} [N]")
print(f"Torque on target: {interaction.torque_on_a_Nm} [N m]")

# periodic2 を明示指定する場合
interaction_p = b.calc_coulomb(
    target=0, source=1,
    periodic2={"axes": [0, 1], "lengths": [0.01, 0.01], "image_layers": 2},
)

6. 電場計算

6.1 compute_electric_field_points(result, points, *, softening, chunk_size, periodic2)

任意 3D 点での電場ベクトルを、表面電荷からクーロン則で直接計算します。

計算式: E(r) = K * sum_j q_j * (r - r_j) / |r - r_j|^3

ここで r_j は三角形要素 j の重心、q_j は要素電荷です。

戻り値: ndarray (n_points, 3) [V/m]

periodic2 モードでは、サンプリング点を周期セルに wrap した上で、ソース電荷の画像シェルを ix in [-nimg, nimg], iy in [-nimg, nimg] で重畳します。

使用例

import numpy as np
from beach import Beach

b = Beach("outputs/latest")

# グリッド点での電場計算
x = np.linspace(0.0, 0.01, 50)
y = np.linspace(0.0, 0.01, 50)
xx, yy = np.meshgrid(x, y)
zz = np.full_like(xx, 0.005)
points = np.column_stack([xx.ravel(), yy.ravel(), zz.ravel()])

efield = b.compute_electric_field(points)
print(f"Shape: {efield.shape}")   # (2500, 3)
print(f"E-field [V/m]: {efield[0]}")

7. 電気力線追跡

7.1 trace_field_lines(result, seed_points, *, ds, max_steps, softening, periodic2, direction, box_min, box_max)

シード点から電場方向（または逆方向）に RK4 積分で電気力線を追跡します。

戻り値: list[ndarray] -- 各要素は shape (n_points_i, 3) の力線座標 [m]

追跡アルゴリズム

• 4 次 Runge-Kutta 法 (RK4) で電場の単位ベクトル方向に ds ずつ進行
• 各 RK4 ステージで電場ノルムが 1e-30 未満になったら打ち切り
• direction="both" の場合は forward と backward を接合（シード点の重複を除去）
• box_min / box_max を超えた時点で打ち切り

制約事項

• Python 側での直接和計算であり、大規模メッシュ（数万要素以上）では計算時間が長くなります
• Fortran の treecode/fmm は使用しません。Python 側の電場計算は要素重心の点電荷による direct 和のみです
• periodic2 では explicit image shell のみを再構成し、oracle residual（Ewald 遠方補正）は Python 側では再現しません

使用例

import numpy as np
from beach import Beach

b = Beach("outputs/latest")

# シード点を手動指定
seeds = np.array([
    [0.005, 0.005, 0.008],
    [0.005, 0.005, 0.002],
])

lines = b.trace_field_lines(seeds, max_steps=1000)
print(f"力線数: {len(lines)}")
for i, line in enumerate(lines):
    print(f"  力線 {i}: {line.shape[0]} 点")

7.2 plot_field_lines_3d(result, seed_points, *, ...)

電気力線を 3D 描画し、オプションでメッシュ表面を電荷密度で着色してオーバーレイします。

戻り値: (figure, axes) -- matplotlib の Figure / Axes3D

描画内容

• 各力線は線として描画。line_color=None の場合は力線ごとに line_cmap で色分け
• 力線の中間点に方向矢印（quiver）を描画
• シード点を赤色の散布点として描画
• show_mesh=True の場合、三角形メッシュを面電荷密度 q / A で着色し半透明で重ねる

使用例

import numpy as np
from beach import Beach

b = Beach("outputs/latest")

seeds = np.array([
    [0.005, 0.005, 0.008],
    [0.003, 0.007, 0.006],
    [0.007, 0.003, 0.006],
])

fig, ax = b.plot_field_lines(
    seeds,
    max_steps=800,
    direction="both",
    show_mesh=True,
    mesh_alpha=0.3,
    line_cmap="viridis",
    view_elev=30,
    view_azim=-45,
)
fig.savefig("field_lines.png", dpi=150)

8. periodic2 パラメータ仕様

電位再構成、Coulomb 力計算、電場計算、電気力線追跡のすべてで共通の periodic2 パラメータが利用できます。

8.1 自動判定（periodic2=None）

デフォルトの None では、出力ディレクトリ近傍の beach.toml を探索し、sim.field_bc_mode="periodic2" が設定されている場合に自動的に周期境界設定を適用します。 設定ファイルが見つからない場合や field_bc_mode が periodic2 でない場合は自由空間モードで計算します。

8.2 明示指定

periodic2 は以下のキーを持つ Mapping で指定します。

origins と box_min が両方指定された場合は origins が優先されます。

使用例

p2 = {
    "axes": [0, 1],
    "lengths": [0.01, 0.01],
    "image_layers": 2,
}
potential = b.compute_potential(periodic2=p2)
efield = b.compute_electric_field(points, periodic2=p2)
interaction = b.calc_coulomb(target=0, source=1, periodic2=p2)
lines = b.trace_field_lines(seeds, periodic2=p2)

8.3 Python 側の periodic2 実装の制限

• Python 側では explicit image shell による直接和のみで周期和を再構成します
• Fortran 側 FMM の m2l_root_oracle による Ewald 遠方補正は Python 側では再現されません。far_correction は設定の互換性のために保持されますが、計算に影響しません
• 大きな image_layers を指定するほど精度は向上しますが、計算量は (2*N+1)^2 倍に増加します

9. Coulomb mobility 解析

9.1 analyze_coulomb_mobility(result, *, step, softening, config_path, gravity, support_normal, ...)

オブジェクト単位で Coulomb 力による滑り・転がり・浮上の傾向を解析します。

戻り値: CoulombMobilityAnalysis (.records に CoulombMobilityRecord のタプルを格納)

10. 可視化関数

10.1 電荷/電位メッシュ描画

fig, ax = b.plot_mesh(cmap="coolwarm")                        # 電荷密度
fig, ax = b.plot_potential(reference_point="species1_injection_center")  # 電位

10.2 電位断面

fig, axes = b.plot_potential_slices(
    box_min=[0, 0, 0], box_max=[0.01, 0.01, 0.01],
    xy_z=0.005,
)

10.3 履歴アニメーション

gif_path = b.animate_mesh("charge_animation.gif", quantity="charge", fps=10)

10.4 Coulomb 力行列

fig, ax = b.plot_coulomb_force_matrix(component="z")

11. CLI コマンド

11.1 統一 CLI (beachx)

v1.0.0 以降は beachx 統一 CLI を推奨します。

11.2 旧 CLI（非推奨）

以下の旧エントリポイントは後方互換のため残されていますが、将来のバージョンで削除される可能性があります。

12. 物理定数