Fortran パラメータファイル仕様（beach.toml）

この文書は、現行実装（Fortran 実行系）で推奨する設定方法をまとめたものです。
「以前の書き方との互換」は最後に短く載せ、本文は初見向けに現在の推奨仕様だけを先に説明します。

beach 自体が読むのは最終的な beach.toml です。 Python 側の beachx config render を使う場合は、case.toml から preset 合成でこの beach.toml を生成できます。 高水準記法（box_origin / box_size、face_fraction、mesh.groups.* など）は case.toml / preset 側でのみ使い、render 時に通常の数値キーへ解決されます。

case.toml、preset、beachx config / beachx preset、高水準記法の全体像は beachx config / preset / 高水準記法ガイド を参照してください。 この文書では、render 後の 最終 beach.toml に残るキー を中心に説明します。

1. 読み込みルール

• beach .../config.toml で明示指定できます。
• 引数なし実行時は、カレントディレクトリの beach.toml を自動で読み込みます。
• 開発時は fpm run -- .../config.toml でも同じ設定読込ルールです。
• 本実装は TOML のうち key = value とセクション/配列テーブルを使う軽量パーサです。
• 未知のセクション名やキー名はエラーになります。キーの打ち間違いを検出しやすい挙動です。

Editor schema

• JSON Schema は schemas/beach.schema.json に同梱しています。
• preset 合成レイヤの case.toml / preset 用には schemas/beach.case.schema.json と schemas/beach.preset.schema.json もあります。
• VS Code の Even Better TOML / Taplo では、各 beach.toml の先頭へ #:schema ... コメントを置くと補完・型検証・必須項目チェックが有効になります。
• beachx config init / beachx config render / beachx preset new / beachx preset save が生成するファイルにも、対応する #:schema ... コメントを自動で付与します。
• BEACH の Fortran パーサは「最初のセクションより前の key = value」を受け付けないため、"$schema" = "..." は使わずコメント directive を使ってください。

ローカル相対パスの例:

#:schema ../schemas/beach.schema.json

• GitHub Raw を使う例:

#:schema https://raw.githubusercontent.com/Nkzono99/BEACH/main/schemas/beach.schema.json

• 相対パスは、その beach.toml 自身から見た相対パスです。
• examples/beach.toml は Raw URL 版を使っています。ローカル未公開の変更を即座に見たい場合は、相対パス版へ切り替えてください。
• outputs/.../beach.toml のような深い場所で相対パスを使うなら、たとえば ../../schemas/beach.schema.json のように調整してください。

2. 初見向けの最小推奨例

まずは reservoir_face（物理流入ベース）を推奨します。

[sim]
dt = 2.0e-8
batch_duration_step = 60000.0
batch_count = 100
max_step = 10000
softening = 1.0e-6
use_box = true
box_min = [0.0, 0.0, 0.0]
box_max = [1.0, 1.0, 10.0]
bc_x_low = "periodic"
bc_x_high = "periodic"
bc_y_low = "periodic"
bc_y_high = "periodic"
bc_z_low = "open"
bc_z_high = "open"
rng_seed = 12345
field_solver = "fmm"
field_bc_mode = "periodic2"
field_periodic_far_correction = "none"

[[particles.species]]
source_mode = "reservoir_face"
number_density_cm3 = 5.0
temperature_ev = 10.0
q_particle = -1.602176634e-19
m_particle = 9.10938356e-31
target_macro_particles_per_batch = 5000
inject_face = "z_high"
pos_low = [0.0, 0.0, 10.0]
pos_high = [1.0, 1.0, 10.0]
drift_velocity = [0.0, 0.0, -4.0e5]

[[particles.species]]
source_mode = "reservoir_face"
number_density_cm3 = 5.0
temperature_ev = 10.0
q_particle = 1.602176634e-19
m_particle = 1.672482821616e-27
target_macro_particles_per_batch = -1
inject_face = "z_high"
pos_low = [0.0, 0.0, 10.0]
pos_high = [1.0, 1.0, 10.0]
drift_velocity = [0.0, 0.0, -4.0e5]

[mesh]
mode = "template"

[[mesh.templates]]
kind = "plane"
enabled = true
size_x = 1.0
size_y = 1.0
nx = 20
ny = 20
center = [0.5, 0.5, 0.02]

[output]
write_files = true
write_mesh_potential = false
dir = "outputs/latest"
history_stride = 1

3. セクションとキー

3.1 [sim]

batch_duration の解決ルール:

• batch_duration と batch_duration_step の同時指定はエラーです。
• batch_duration_step 指定時は batch_duration = dt * batch_duration_step に解決します。
• reservoir_face / photo_raycast を使う場合、解決後の batch_duration > 0 が必須です。
• sheath_injection_model != "none" は現状 reservoir_potential_model = "none" と組み合わせてください。

重要な実行挙動:

• 実行ループは batch_count 分だけ進みます。
• tol_rel は出力監視値であり、現行実装では早期終了条件には使いません。

tree_theta / tree_leaf_max の自動推定値:

• nelem < 1500: theta = 0.40, leaf_max = 12
• 1500 <= nelem < 10000: theta = 0.50, leaf_max = 16
• 10000 <= nelem < 50000: theta = 0.58, leaf_max = 20
• 50000 <= nelem: theta = 0.65, leaf_max = 24
• field_bc_mode = "periodic2" でも同じ表を使い、追加の periodic2 専用 clamp は行いません。
• field_bc_mode = "periodic2" の mesh は runtime で collision 用 canonical unwrapped 表現へ平行移動してから ray-triangle 判定します。raw 頂点は periodic 軸で box 外を含んでも構いませんが、triangle を頂点ごとに mod 折り返すことはしません。

3.2 [[particles.species]]

[[particles.species]] は 1 件以上必須です。

共通キー

source_mode = "volume_seed"

制約:

• 有効 species 全体で npcls_per_step 合計が 1 以上必要です（reservoir_face / photo_raycast を使わない場合）。
• target_macro_particles_per_batch は使用できません。

source_mode = "reservoir_face"

制約:

• sim.use_box = true 必須
• sim.batch_duration > 0 必須
• inject_face 必須
• pos_low / pos_high は指定 face 上になければエラー
• w_particle と target_macro_particles_per_batch は同時指定不可
• target_macro_particles_per_batch = -1 は species[2] 以降のみ可（species[1] の w_particle を共有）

粒子数決定（1種あたり）:

• 期待マクロ粒子数 n_macro_expected = gamma_in * A * batch_duration / w_particle
• 実際の注入数は残差繰越つきで floor(residual + n_macro_expected)
• target_macro_particles_per_batch > 0 のときは、その値になるよう w_particle を自動計算

source_mode = "photo_raycast"

制約:

• sim.use_box = true 必須
• sim.batch_duration > 0 必須
• emit_current_density_a_m2 > 0, rays_per_batch > 0 必須
• inject_face 必須
• q_particle は非ゼロ、m_particle > 0 必須
• ray_direction 指定時は正規化可能で、注入面内向き法線への内積が正であること
• npcls_per_step / number_density_* / w_particle / target_macro_particles_per_batch は使用不可

photo_raycast の重み:

• w_hit = J_perp * A_perp * batch_duration / (|q_particle| * rays_per_batch)
• 実際の放出数はレイの命中率で決まるため、バッチごとの生成粒子数は rays_per_batch 以下になります。
• field_bc_mode = "periodic2" のとき、periodic image に命中しても放出位置は primary cell に wrap した hit 座標を使います。

sim.sheath_injection_model

sim.sheath_injection_model は既存の reservoir_face / photo_raycast species を束ねて、 シースに対応する流束・法線速度 cutoff を上書きする共有設定です。

• zhao_auto / zhao_a / zhao_b / zhao_c
• Zhao の 1D 光電子シース条件を使います。
• 自動検出対象:
  • 最初の負電荷 reservoir_face species を solar-wind electron
  • 最初の正電荷 reservoir_face species を ion
  • 最初の負電荷 photo_raycast species を photoelectron
• electron reservoir species は、流束計算に使う有効密度が Zhao 解の n_swe_inf へ置き換わります。
• electron reservoir species の法線速度分布は Zhao の障壁に応じた vmin_normal 付きになります。
• sheath_reference_coordinate を明示した場合は、指定平面から reservoir 境界までの Zhao 局所状態を再構成し、electron reservoir は局所 phi(z) に応じた有効密度と cutoff、ion reservoir は局所密度・局所法線速度・冷たいビーム近似へ更新されます。
• photoelectron photo_raycast species は、emit_current_density_a_m2 が Zhao の自由光電子電流へ上書きされ、normal_drift_speed は 0 として扱います。
• floating_no_photo
• 光電子を含まない簡易 floating sheath です。
• 最初の負電荷 / 正電荷 reservoir_face species の電流釣り合いから負の浮遊電位を解き、electron reservoir species へ cutoff を掛けます。
• photo_raycast species があっても放出電流は 0 とみなします。

注意:

• Zhao 系モデルは temperature_ev/temperature_k, number_density_*, drift_velocity, m_particle, q_particle といった既存 species パラメータを背景プラズマ条件として再利用します。
• sheath_reference_coordinate を指定すると、共有 inject_face の法線軸に沿ってその座標を基準平面に使います。たとえば inject_face = "z_high" かつ sheath_reference_coordinate = 0.02 なら、平面 z = 0.02 を z_sheath = 0 とみなします。未指定時は inject_face が指す box 境界面座標を使います。
• sheath_reference_coordinate を未指定のまま Zhao を使う場合は、従来どおり共有 cutoff ベースの補正のみを適用します。局所 VDF の変形を反映したい場合は基準平面を明示してください。
• 現在の Fortran 実装では、Type-A の局所プロファイルは 1 次積分から、Type-B/C の局所プロファイルは Zhao の単調分枝を 1 次積分で再構成して評価します。Python 実装の BVP 解と十分近い値を使いますが、完全に同一の離散化ではありません。
• zhao_auto は alpha < 20 deg で C -> A -> B、それ以外では A -> B -> C の順に分枝解を試みます。

3.3 [mesh]

mode = "auto" のときは obj_path が存在すれば OBJ、なければ template を使います。

OBJ メッシュの変換順序は scale → rotate → offset です: v_new = R(rotation) * (v_old * scale) + offset。 CRLF 改行の OBJ ファイルもサポートしています。面行は f v, f v/vt, f v/vt/vn, f v//vn のいずれの形式にも対応し、四角形以上のポリゴンはファン三角形分割されます。

3.4 [[mesh.templates]]

共通キー:

• enabled (bool)
• kind (plane / plate_hole / disk / annulus / box / cylinder / sphere)
• center (float[3])

kind ごとの主要キー:

• plane: size_x, size_y, nx, ny
• plate_hole: size_x, size_y, radius, n_theta, n_r
• disk: radius, n_theta, n_r
• annulus: radius, inner_radius, n_theta, n_r
• box: size, nx, ny, nz
• cylinder: radius, height, n_theta, n_z, cap, cap_top, cap_bottom
• sphere: radius, n_lon, n_lat

注意:

• [[mesh.templates]] を書いた場合、実際に使うテンプレート数は「定義した件数」で解決されます。

3.5 [output]

出力ファイル:

• summary.txt
• charges.csv
• mesh_potential.csv（write_mesh_potential = true のとき）
• mesh_triangles.csv
• mesh_sources.csv
• charge_history.csv（history_stride > 0 のとき）
• potential_history.csv（write_potential_history = true かつ history_stride > 0 のとき）
• rng_state.txt
• macro_residuals.csv

mesh_triangles.csv には mesh_id 列が追加され、mesh_sources.csv で mesh_id ごとの元メッシュ種別と要素数を確認できます。

mesh_potential.csv は要素重心での電位 [V] を記録します。自己項は softening > 0 なら 1/softening、そうでなければ面積等価半径近似を使います。periodic2 では explicit image shell に加えて、field_periodic_far_correction が auto または m2l_root_oracle のときは exact Ewald residual も加えます。none では residual を加えません。

potential_history.csv は charge_history.csv と同じ history_stride で要素ごとの電位を記録します。フォーマットは batch,elem_idx,potential_V。history_stride ごとに field_solver%refresh + compute_mesh_potential が実行されるため、有効化すると計算コストが増加します。

MPI実行（world_size > 1）では乱数状態・残差はrank別ファイルになります。

• rng_state_rank00000.txt, rng_state_rank00001.txt, ...
• macro_residuals_rank00000.csv, macro_residuals_rank00001.csv, ...

また、summary.txt には mpi_world_size が記録されます。

resume = true の要件:

• write_files = true 必須
• output.dir に summary.txt / charges.csv / rng_state.txt が必要
• macro_residuals.csv は存在すれば読み込みます

MPI実行での追加要件:

• summary.txt の mpi_world_size が現在のrank数と一致している必要があります
• 各rankに対応する rng_state_rankNNNNN.txt が必要です
• macro_residuals_rankNNNNN.csv は存在すれば読み込みます

4. キー検証

• 未知のセクション名・キー名はすべてエラーになります。
• v0.3.0 以降は旧キー互換を持たず、旧名は「未知キー」として扱います。
• [particles] は [[particles.species]] のコンテナとしてのみ使い、[particles] 直下に key = value は書かないでください。