公開 API: beach

通常の後処理では from beach import Beach, load_run のように公開名を import します。 以下の一覧は beach.__all__ に従うため、新しい公開名も実装から取り込みます。

BEACH (BEM + Accumulated CHarge) Python package.

The public names below are defined in the layer subpackages beach.io, beach.native, beach.analysis, and beach.plot, plus the Beach facade. They are loaded on first access (PEP 562), so lightweight subpackages such as beach.config and beach.tooling import without numpy or matplotlib.

beach.load_top_reference_history(path)

Read z-high plane samples; absent files return None, header-only files ().

The released 3.0 eight-column format defaults the two switch mismatch values to zero, matching the simulator's persisted-history migration.

パラメータ:

path (str | Path)

戻り値の型:

tuple[TopReferenceHistoryEntry, ...] | None

beach.load_fixed_current_history(path)

Read fixed-current window diagnostics, including the defined NaN ratio for zero tracking.

パラメータ:

path (str | Path)

戻り値の型:

tuple[FixedCurrentHistoryEntry, ...] | None

beach.load_matching_plane_spectrum_history(path)

Read nonempty photoelectron energy bins; absent files return None.

パラメータ:

path (str | Path)

戻り値の型:

tuple[MatchingPlaneSpectrumHistoryEntry, ...] | None

beach.load_performance_profile(path)

Load one performance_profile.csv file.

パラメータ:

path (str | Path)

戻り値の型:

tuple[dict[str, str], list[dict[str, str | float]]]

class beach.SummaryField(key, attribute, group, kind, default=None, required=False)

One persisted summary scalar and its destination in RunResult.

kind states the scalar contract; nonnegative_float and nonnegative_int reject negative values. Missing optional values use default. Complex field/matching-plane receipts have their own schema.

パラメータ:

• key (str)

• attribute (str)

• group (Literal['summary', 'receipts', 'diagnostics', 'field'])

• kind (Literal['nonnegative_int', 'nonnegative_float', 'float', 'bool', 'str', 'model'])

• default (str | int | float | bool | None)

• required (bool)

default: str | int | float | bool | None = None

required: bool = False

key: str

attribute: str

group: Literal['summary', 'receipts', 'diagnostics', 'field']

kind: Literal['nonnegative_int', 'nonnegative_float', 'float', 'bool', 'str', 'model']

beach.summary_fields_markdown()

Generate the summary scalar reference table used in OutputReference.md.

戻り値の型:

str

class beach.RunContext(result, requested_config_path=None)

Resolved run plus lazily loaded, cached nearby configuration.

パラメータ:

• result (RunResult)

• requested_config_path (Path | None)

charges_at(step)

パラメータ:

step (int | None)

戻り値の型:

ndarray

property config: Mapping[str, object] | None

property config_path: Path | None

property domain: Mapping[str, object] | None

property field_boundary: Mapping[str, object] | None

classmethod from_value(value, *, config_path=None)

Return the context of a result, a context, or a Beach session.

A Beach contributes its own Beach.context, so its config path and cached config carry over. An explicit config_path replaces the inherited one.

パラメータ:

• value (RunResult | object)

• config_path (str | Path | None)

戻り値の型:

RunContext

mesh_ids_or_default()

戻り値の型:

ndarray

property output_dir: Path

requested_config_path: Path | None = None

require_history()

戻り値の型:

BatchHistory

require_triangle_source_model()

戻り値の型:

None

require_triangles()

戻り値の型:

ndarray

property sim: Mapping[str, object] | None

result: RunResult

class beach.BatchHistory(path, *, mesh_nelem, value_column='charge_C')

Lazy accessor for per-element CSV values with batch-step indexing.

パラメータ:

• path (pathlib.Path) -- Path to charge_history.csv or potential_history.csv.

• mesh_nelem (int) -- Number of mesh elements. Used to shape per-step vectors.

• value_column (str, default "charge_C") -- Value column to read, for example "charge_C" or "potential_V". Histories without processed-particle/relative-change metadata expose None for those two properties.

as_array()

Materialize full history as (mesh_nelem, n_snapshots) array.

戻り値:

Full value history matrix.

戻り値の型:

numpy.ndarray

property batch_indices: ndarray

Return batch indices corresponding to available history snapshots.

戻り値:

Batch indices with shape (n_snapshots,).

戻り値の型:

numpy.ndarray

classmethod from_arrays(path, *, mesh_nelem, history, batch_indices, processed_particles_by_batch=None, rel_change_by_batch=None, value_column='charge_C')

Construct an in-memory history object without reading CSV from disk.

パラメータ:

• path (pathlib.Path) -- Virtual history path metadata.

• mesh_nelem (int) -- Number of mesh elements.

• history (numpy.ndarray) -- Charge history matrix with shape (mesh_nelem, n_snapshots).

• processed_particles_by_batch (numpy.ndarray) -- Processed-particle counts for each snapshot.

• rel_change_by_batch (numpy.ndarray) -- Relative-change values for each snapshot.

• batch_indices (numpy.ndarray) -- Batch index values for each snapshot.

• value_column (str)

戻り値:

Initialized in-memory history object.

戻り値の型:

BatchHistory

get_step(step)

Return per-element values at one batch step.

パラメータ:

step (int) -- Batch step to read. -1 selects the latest available step.

戻り値:

Per-element value array with shape (mesh_nelem,).

戻り値の型:

numpy.ndarray

例外:

ValueError -- If history is missing/empty, or the requested step is unavailable.

property has_data: bool

Return whether history snapshots exist.

戻り値:

True when at least one snapshot is available.

戻り値の型:

bool

property processed_particles_by_batch: ndarray | None

Return processed-particle counts aligned with batch_indices.

戻り値:

Processed-particle counts with shape (n_snapshots,).

戻り値の型:

numpy.ndarray

property rel_change_by_batch: ndarray | None

Return per-batch relative charge-change metrics from history.

戻り値:

Relative-change values with shape (n_snapshots,).

戻り値の型:

numpy.ndarray

beach.list_runs(root)

List directories that look like valid Fortran output runs.

パラメータ:

root (str or pathlib.Path) -- Root directory to scan.

戻り値:

Directories containing both summary.txt and charges.csv.

戻り値の型:

list[pathlib.Path]

beach.load_run(directory)

Read one output directory without constructing a native kernel (light).

パラメータ:

directory (str or pathlib.Path) -- Output directory containing summary.txt and charges.csv.

戻り値:

Counts, geometry, receipts, diagnostics and lazy charge/potential histories. Missing optional CSV products are None; header-only diagnostic CSVs are empty tuples. Persisted outputs from released versions remain readable.

戻り値の型:

RunResult

例外:

• FileNotFoundError -- Required files are missing.

• ValueError -- Required summary keys are missing or persisted values are malformed.

class beach.ChargeLedgerEntry(batch, species_idx, injected_from_remote_c, emitted_from_surface_c, absorbed_on_surface_c, escaped_to_infinity_c, discarded_unresolved_c, injected_count, emitted_count, absorbed_count, escaped_count, discarded_unresolved_count, neutral_return_correction_c=0.0, neutral_return_weight_scale=1.0, neutral_return_unresolved_fraction=0.0, fixed_absorbed_target_charge_c=0.0, fixed_absorbed_applied_charge_c=0.0, fixed_absorbed_weight_scale=1.0, fixed_emission_target_charge_c=0.0, fixed_emission_applied_charge_c=0.0, fixed_emission_weight_scale=1.0, fixed_escape_target_charge_c=0.0, fixed_escape_applied_charge_c=0.0, fixed_escape_correction_c=0.0, fixed_current_correction_c=0.0)

One species row from charge_ledger.csv.

パラメータ:

• batch (int)

• species_idx (int)

• injected_from_remote_c (float)

• emitted_from_surface_c (float)

• absorbed_on_surface_c (float)

• escaped_to_infinity_c (float)

• discarded_unresolved_c (float)

• injected_count (int)

• emitted_count (int)

• absorbed_count (int)

• escaped_count (int)

• discarded_unresolved_count (int)

• neutral_return_correction_c (float)

• neutral_return_weight_scale (float)

• neutral_return_unresolved_fraction (float)

• fixed_absorbed_target_charge_c (float)

• fixed_absorbed_applied_charge_c (float)

• fixed_absorbed_weight_scale (float)

• fixed_emission_target_charge_c (float)

• fixed_emission_applied_charge_c (float)

• fixed_emission_weight_scale (float)

• fixed_escape_target_charge_c (float)

• fixed_escape_applied_charge_c (float)

• fixed_escape_correction_c (float)

• fixed_current_correction_c (float)

fixed_absorbed_applied_charge_c: float = 0.0

fixed_absorbed_target_charge_c: float = 0.0

fixed_absorbed_weight_scale: float = 1.0

fixed_current_correction_c: float = 0.0

fixed_emission_applied_charge_c: float = 0.0

fixed_emission_target_charge_c: float = 0.0

fixed_emission_weight_scale: float = 1.0

fixed_escape_applied_charge_c: float = 0.0

fixed_escape_correction_c: float = 0.0

fixed_escape_target_charge_c: float = 0.0

neutral_return_correction_c: float = 0.0

neutral_return_unresolved_fraction: float = 0.0

neutral_return_weight_scale: float = 1.0

batch: int

species_idx: int

injected_from_remote_c: float

emitted_from_surface_c: float

absorbed_on_surface_c: float

escaped_to_infinity_c: float

discarded_unresolved_c: float

injected_count: int

emitted_count: int

absorbed_count: int

escaped_count: int

discarded_unresolved_count: int

class beach.CoulombInteraction(group_a_mesh_ids, group_b_mesh_ids, step, torque_origin_m, force_on_a_N, force_on_b_N, torque_on_a_Nm, torque_on_b_Nm, mean_force_on_a_per_element_N, mean_torque_on_a_per_element_Nm)

Coulomb force/torque summary between two mesh groups.

変数:

• group_a_mesh_ids (tuple of int) -- Mesh ids used as the target group.

• group_b_mesh_ids (tuple of int) -- Mesh ids used as the source group.

• step (int or None) -- History step used for the interaction snapshot.

• torque_origin_m (numpy.ndarray) -- Torque origin in meters with shape (3,).

• force_on_a_N (numpy.ndarray) -- Net force on group A in newtons with shape (3,).

• force_on_b_N (numpy.ndarray) -- Net force on group B in newtons with shape (3,).

• torque_on_a_Nm (numpy.ndarray) -- Net torque on group A in newton-meters with shape (3,).

• torque_on_b_Nm (numpy.ndarray) -- Net torque on group B in newton-meters with shape (3,).

• mean_force_on_a_per_element_N (numpy.ndarray) -- Mean force per target element in newtons with shape (3,).

• mean_torque_on_a_per_element_Nm (numpy.ndarray) -- Mean torque per target element in newton-meters with shape (3,).

パラメータ:

• group_a_mesh_ids (tuple[int, ...])

• group_b_mesh_ids (tuple[int, ...])

• step (int | None)

• torque_origin_m (ndarray)

• force_on_a_N (ndarray)

• force_on_b_N (ndarray)

• torque_on_a_Nm (ndarray)

• torque_on_b_Nm (ndarray)

• mean_force_on_a_per_element_N (ndarray)

• mean_torque_on_a_per_element_Nm (ndarray)

group_a_mesh_ids: tuple[int, ...]

group_b_mesh_ids: tuple[int, ...]

step: int | None

torque_origin_m: ndarray

force_on_a_N: ndarray

force_on_b_N: ndarray

torque_on_a_Nm: ndarray

torque_on_b_Nm: ndarray

mean_force_on_a_per_element_N: ndarray

mean_torque_on_a_per_element_Nm: ndarray

class beach.CoulombMobilityAnalysis(step, gravity_m_s2, support_normal_m, support_kinds, density_kg_m3, mu_static, mu_roll, adhesion_force_N, records)

Collection of per-object Coulomb mobility records.

変数:

• step (int or None) -- History step used for the analysis snapshot.

• gravity_m_s2 (numpy.ndarray) -- Gravity vector in meters per second squared with shape (3,).

• support_normal_m (numpy.ndarray) -- Unit support normal with shape (3,).

• support_kinds (tuple of str) -- Object kinds treated as supports and excluded by default from targets.

• density_kg_m3 (float or None) -- Bulk density used for mass estimation.

• mu_static (float or None) -- Static-friction coefficient used for slide checks.

• mu_roll (float or None) -- Rolling-resistance coefficient used for roll checks.

• adhesion_force_N (float) -- Additional normal adhesion resisting lift.

• records (tuple of CoulombMobilityRecord) -- Per-object analysis records.

パラメータ:

• step (int | None)

• gravity_m_s2 (ndarray)

• support_normal_m (ndarray)

• support_kinds (tuple[str, ...])

• density_kg_m3 (float | None)

• mu_static (float | None)

• mu_roll (float | None)

• adhesion_force_N (float)

• records (tuple[CoulombMobilityRecord, ...])

step: int | None

gravity_m_s2: ndarray

support_normal_m: ndarray

support_kinds: tuple[str, ...]

density_kg_m3: float | None

mu_static: float | None

mu_roll: float | None

adhesion_force_N: float

records: tuple[CoulombMobilityRecord, ...]

class beach.CoulombMobilityRecord(mesh_id, label, kind, step, center_m, force_N, torque_Nm, force_normal_N, force_tangent_N, torque_normal_Nm, torque_tangent_Nm, mass_kg, characteristic_radius_m, weight_support_N, resisting_normal_N, effective_normal_load_N, lift_ratio, slide_ratio, roll_ratio, notes=())

Per-object Coulomb mobility summary.

変数:

• mesh_id (int) -- Mesh identifier of the analyzed object.

• label (str) -- Human-readable object label.

• kind (str) -- Object kind resolved from beach.toml or mesh_sources.csv.

• step (int or None) -- History step used for the analysis snapshot.

• center_m (numpy.ndarray) -- Object centroid in meters with shape (3,).

• force_N (numpy.ndarray) -- Net Coulomb force in newtons with shape (3,).

• torque_Nm (numpy.ndarray) -- Net Coulomb torque about object center in newton-meters with shape (3,).

• force_normal_N (float) -- Force component along support normal. Positive means lift direction.

• force_tangent_N (float) -- Tangential-force magnitude relative to the support normal.

• torque_normal_Nm (float) -- Torque component along support normal.

• torque_tangent_Nm (float) -- Tangential-torque magnitude relative to the support normal.

• mass_kg (float or None) -- Estimated object mass. None when geometry or density is unavailable.

• characteristic_radius_m (float or None) -- Characteristic radius used for rolling metrics when available.

• weight_support_N (float or None) -- Weight component resisted by the support normal.

• resisting_normal_N (float or None) -- Baseline normal resistance used for lift checks (typically weight + adhesion).

• effective_normal_load_N (float or None) -- Remaining compressive normal load after Coulomb lift is applied.

• lift_ratio (float or None) -- max(force_normal, 0) / resisting_normal when available.

• slide_ratio (float or None) -- force_tangent / (mu_static * effective_normal_load) when available.

• roll_ratio (float or None) -- torque_tangent / (mu_roll * effective_normal_load * radius) when available.

• notes (tuple of str) -- Diagnostic notes about unavailable assumptions or approximations.

パラメータ:

• mesh_id (int)

• label (str)

• kind (str)

• step (int | None)

• center_m (ndarray)

• force_N (ndarray)

• torque_Nm (ndarray)

• force_normal_N (float)

• force_tangent_N (float)

• torque_normal_Nm (float)

• torque_tangent_Nm (float)

• mass_kg (float | None)

• characteristic_radius_m (float | None)

• weight_support_N (float | None)

• resisting_normal_N (float | None)

• effective_normal_load_N (float | None)

• lift_ratio (float | None)

• slide_ratio (float | None)

• roll_ratio (float | None)

• notes (tuple[str, ...])

notes: tuple[str, ...] = ()

mesh_id: int

label: str

kind: str

step: int | None

center_m: ndarray

force_N: ndarray

torque_Nm: ndarray

force_normal_N: float

force_tangent_N: float

torque_normal_Nm: float

torque_tangent_Nm: float

mass_kg: float | None

characteristic_radius_m: float | None

weight_support_N: float | None

resisting_normal_N: float | None

effective_normal_load_N: float | None

lift_ratio: float | None

slide_ratio: float | None

roll_ratio: float | None

class beach.FieldReconstructionReceipt(schema_version, resolved_field_solver, fmm_expansion_order, field_bc_mode, tree_theta, tree_leaf_max, external_e0_v_m, use_box, box_min_m, box_max_m, boundary_low, boundary_high, periodic_image_layers, periodic_far_correction, periodic_nonzero_mode_backend, periodic_zero_mode_policy, periodic_lower_boundary_model, periodic_reference_mode_layers, periodic_panel_quadrature_order, periodic_ewald_alpha, periodic_ewald_layers, periodic_cache_dir, periodic_generation_tolerance, upper_fourier_switch_active=False, upper_fourier_switch_height_m=0.0, upper_fourier_switch_mode_layers=0)

Resolved simulator settings required to reconstruct its electric field.

パラメータ:

• schema_version (int)

• resolved_field_solver (str)

• fmm_expansion_order (int)

• field_bc_mode (str)

• tree_theta (float)

• tree_leaf_max (int)

• external_e0_v_m (tuple[float, float, float])

• use_box (bool)

• box_min_m (tuple[float, float, float])

• box_max_m (tuple[float, float, float])

• boundary_low (tuple[int, int, int])

• boundary_high (tuple[int, int, int])

• periodic_image_layers (int)

• periodic_far_correction (str)

• periodic_nonzero_mode_backend (str)

• periodic_zero_mode_policy (str)

• periodic_lower_boundary_model (str)

• periodic_reference_mode_layers (int)

• periodic_panel_quadrature_order (int)

• periodic_ewald_alpha (float)

• periodic_ewald_layers (int)

• periodic_cache_dir (str)

• periodic_generation_tolerance (float)

• upper_fourier_switch_active (bool)

• upper_fourier_switch_height_m (float)

• upper_fourier_switch_mode_layers (int)

as_legacy_sim_mapping()

Return the combined simulator mapping consumed by field utilities.

戻り値の型:

dict[str, object]

upper_fourier_switch_active: bool = False

upper_fourier_switch_height_m: float = 0.0

upper_fourier_switch_mode_layers: int = 0

schema_version: int

resolved_field_solver: str

fmm_expansion_order: int

field_bc_mode: str

tree_theta: float

tree_leaf_max: int

external_e0_v_m: tuple[float, float, float]

use_box: bool

box_min_m: tuple[float, float, float]

box_max_m: tuple[float, float, float]

boundary_low: tuple[int, int, int]

boundary_high: tuple[int, int, int]

periodic_image_layers: int

periodic_far_correction: str

periodic_nonzero_mode_backend: str

periodic_zero_mode_policy: str

periodic_lower_boundary_model: str

periodic_reference_mode_layers: int

periodic_panel_quadrature_order: int

periodic_ewald_alpha: float

periodic_ewald_layers: int

periodic_cache_dir: str

periodic_generation_tolerance: float

class beach.RunResult(directory, summary, charges, mesh=<factory>, history=<factory>, receipts=<factory>, diagnostics=<factory>, field=<factory>, ledger=None, matching_plane_history=None, secondary_emission_history=None, top_reference_history=None, matching_plane_spectrum_history=None, fixed_current_history=None, performance_profile=None)

Saved output from one BEACH run, grouped by purpose (light: CSV only).

summary contains core counts, mesh contains saved geometry and potentials, history provides lazy BatchHistory accessors, and receipts and diagnostics hold optional settings and monitoring data. Optional CSV files are None when absent and empty tuples when header-only. No native field kernel or matplotlib is loaded by the reader.

パラメータ:

• directory (Path)

• summary (RunSummary)

• charges (ndarray)

• mesh (RunMesh)

• history (RunHistory)

• receipts (RunReceipts)

• diagnostics (RunDiagnostics)

• field (RunField)

• ledger (tuple[ChargeLedgerEntry, ...] | None)

• matching_plane_history (tuple[MatchingPlaneHistoryEntry, ...] | None)

• secondary_emission_history (tuple[SecondaryEmissionHistoryEntry, ...] | None)

• top_reference_history (tuple[TopReferenceHistoryEntry, ...] | None)

• matching_plane_spectrum_history (tuple[MatchingPlaneSpectrumHistoryEntry, ...] | None)

• fixed_current_history (tuple[FixedCurrentHistoryEntry, ...] | None)

• performance_profile (tuple[dict[str, str], list[dict[str, str | float]]] | None)

fixed_current_history: tuple[FixedCurrentHistoryEntry, ...] | None = None

ledger: tuple[ChargeLedgerEntry, ...] | None = None

matching_plane_history: tuple[MatchingPlaneHistoryEntry, ...] | None = None

matching_plane_spectrum_history: tuple[MatchingPlaneSpectrumHistoryEntry, ...] | None = None

performance_profile: tuple[dict[str, str], list[dict[str, str | float]]] | None = None

secondary_emission_history: tuple[SecondaryEmissionHistoryEntry, ...] | None = None

top_reference_history: tuple[TopReferenceHistoryEntry, ...] | None = None

directory: Path

summary: RunSummary

charges: ndarray

mesh: RunMesh

history: RunHistory

receipts: RunReceipts

diagnostics: RunDiagnostics

field: RunField

class beach.RunSummary(mesh_nelem, processed_particles, absorbed, escaped, batches, escaped_boundary=0, survived_max_step=0, last_rel_change=0.0, simulated_time_s=None)

Core counts and accepted simulation time from summary.txt.

パラメータ:

• mesh_nelem (int)

• processed_particles (int)

• absorbed (int)

• escaped (int)

• batches (int)

• escaped_boundary (int)

• survived_max_step (int)

• last_rel_change (float)

• simulated_time_s (float | None)

escaped_boundary: int = 0

last_rel_change: float = 0.0

simulated_time_s: float | None = None

survived_max_step: int = 0

mesh_nelem: int

processed_particles: int

absorbed: int

escaped: int

batches: int

class beach.RunMesh(triangles=None, mesh_ids=None, mesh_sources=None, mesh_potential_v=None)

Saved geometry, per-element mesh ids, materials, and centroid potentials.

Missing optional CSV products are represented by None. Coordinates are in meters and mesh_potential_v is in volts.

パラメータ:

• triangles (ndarray | None)

• mesh_ids (ndarray | None)

• mesh_sources (dict[int, MeshSource] | None)

• mesh_potential_v (ndarray | None)

mesh_ids: ndarray | None = None

mesh_potential_v: ndarray | None = None

mesh_sources: dict[int, MeshSource] | None = None

triangles: ndarray | None = None

class beach.RunHistory(charge=None, potential=None)

Lazy per-element charge and potential histories, absent files as None.

パラメータ:

• charge (BatchHistory | None)

• potential (BatchHistory | None)

charge: BatchHistory | None = None

potential: BatchHistory | None = None

class beach.RunReceipts(checkpoint_schema_version=None, model_fingerprint=None, mesh_fingerprint=None, species_fingerprint=None, field_reconstruction=None, matching_plane_state=None)

Persisted model identity and settings needed for field reconstruction.

パラメータ:

• checkpoint_schema_version (int | None)

• model_fingerprint (str | None)

• mesh_fingerprint (str | None)

• species_fingerprint (str | None)

• field_reconstruction (FieldReconstructionReceipt | None)

• matching_plane_state (MatchingPlaneState | None)

checkpoint_schema_version: int | None = None

field_reconstruction: FieldReconstructionReceipt | None = None

matching_plane_state: MatchingPlaneState | None = None

mesh_fingerprint: str | None = None

model_fingerprint: str | None = None

species_fingerprint: str | None = None

class beach.RunField(source_model='triangle_p0', kernel_id=None)

Saved field source model and native-kernel identifier.

パラメータ:

• source_model (str)

• kernel_id (str | None)

kernel_id: str | None = None

source_model: str = 'triangle_p0'

class beach.RunDiagnostics(charge_ledger_residual_c=None, periodic2_cache_hit=None, periodic2_operator_build_count=None, periodic2_cache_fingerprint=None, periodic2_cache_path=None, periodic2_generation_tolerance=None, multiple_box_events_retry_attempted=0, multiple_box_events_retry_resolved=0, multiple_box_events_soft_discarded=0, multiple_box_events_soft_discarded_abs_charge_c=0.0, multiple_box_events_soft_discard_fraction=0.0, adaptive_nonzero_mode_rejected_trials=0, adaptive_nonzero_mode_last_batch_duration_s=None, adaptive_nonzero_mode_last_potential_step_v=None, adaptive_nonzero_mode_omp_threads=None, periodic2_max_nonzero_mode_potential_step_v=None)

Optional cache, boundary retry, ledger, and adaptive-step diagnostics.

パラメータ:

• charge_ledger_residual_c (float | None)

• periodic2_cache_hit (bool | None)

• periodic2_operator_build_count (int | None)

• periodic2_cache_fingerprint (str | None)

• periodic2_cache_path (str | None)

• periodic2_generation_tolerance (float | None)

• multiple_box_events_retry_attempted (int)

• multiple_box_events_retry_resolved (int)

• multiple_box_events_soft_discarded (int)

• multiple_box_events_soft_discarded_abs_charge_c (float)

• multiple_box_events_soft_discard_fraction (float)

• adaptive_nonzero_mode_rejected_trials (int)

• adaptive_nonzero_mode_last_batch_duration_s (float | None)

• adaptive_nonzero_mode_last_potential_step_v (float | None)

• adaptive_nonzero_mode_omp_threads (int | None)

• periodic2_max_nonzero_mode_potential_step_v (float | None)

adaptive_nonzero_mode_last_batch_duration_s: float | None = None

adaptive_nonzero_mode_last_potential_step_v: float | None = None

adaptive_nonzero_mode_omp_threads: int | None = None

adaptive_nonzero_mode_rejected_trials: int = 0

charge_ledger_residual_c: float | None = None

multiple_box_events_retry_attempted: int = 0

multiple_box_events_retry_resolved: int = 0

multiple_box_events_soft_discard_fraction: float = 0.0

multiple_box_events_soft_discarded: int = 0

multiple_box_events_soft_discarded_abs_charge_c: float = 0.0

periodic2_cache_fingerprint: str | None = None

periodic2_cache_hit: bool | None = None

periodic2_cache_path: str | None = None

periodic2_generation_tolerance: float | None = None

periodic2_max_nonzero_mode_potential_step_v: float | None = None

periodic2_operator_build_count: int | None = None

class beach.TopReferenceHistoryEntry(batch, simulated_time_s, z_high_m, sample_n, potential_mean_v, potential_std_v, potential_min_v, potential_max_v, switch_phi_rms_mismatch_v=0.0, switch_ez_rms_mismatch_v_m=0.0)

One z-high plane potential sample; mismatch fields were added after 3.0.

パラメータ:

• batch (int)

• simulated_time_s (float)

• z_high_m (float)

• sample_n (int)

• potential_mean_v (float)

• potential_std_v (float)

• potential_min_v (float)

• potential_max_v (float)

• switch_phi_rms_mismatch_v (float)

• switch_ez_rms_mismatch_v_m (float)

switch_ez_rms_mismatch_v_m: float = 0.0

switch_phi_rms_mismatch_v: float = 0.0

batch: int

simulated_time_s: float

z_high_m: float

sample_n: int

potential_mean_v: float

potential_std_v: float

potential_min_v: float

potential_max_v: float

class beach.FixedCurrentHistoryEntry(batch, simulated_time_s, window_batches, species_idx, channel, tracked_charge_c, target_charge_c, target_over_tracked)

Tracked and target charge over a history window for one species/channel.

target_over_tracked is NaN when the tracked charge is zero, as written by the simulator. This diagnostic does not participate in restart state.

パラメータ:

• batch (int)

• simulated_time_s (float)

• window_batches (int)

• species_idx (int)

• channel (str)

• tracked_charge_c (float)

• target_charge_c (float)

• target_over_tracked (float)

batch: int

simulated_time_s: float

window_batches: int

species_idx: int

channel: str

tracked_charge_c: float

target_charge_c: float

target_over_tracked: float

class beach.MatchingPlaneSpectrumHistoryEntry(batch, simulated_time_s, bin, energy_low_ev, energy_high_ev, photoelectron_outward_flux_m2_s)

One nonempty outward photoelectron energy bin at an accepted batch.

パラメータ:

• batch (int)

• simulated_time_s (float)

• bin (int)

• energy_low_ev (float)

• energy_high_ev (float)

• photoelectron_outward_flux_m2_s (float)

batch: int

simulated_time_s: float

bin: int

energy_low_ev: float

energy_high_ev: float

photoelectron_outward_flux_m2_s: float

class beach.MatchingPlaneHistoryEntry(batch, simulated_time_s, state)

Matching-plane receipt selected by output.history_stride.

パラメータ:

• batch (int)

• simulated_time_s (float)

• state (MatchingPlaneState)

batch: int

simulated_time_s: float

state: MatchingPlaneState

class beach.MatchingPlaneState(displacement_c_m2, phi_v, electron_inward_flux_m2_s, ion_inward_flux_m2_s, electron_access_potential_v, ion_access_potential_v, photoelectron_barrier_potential_v, photoelectron_outward_flux_m2_s, photoelectron_mean_normal_energy_ev, electron_outward_flux_m2_s, ion_outward_flux_m2_s, photoelectron_return_flux_m2_s, photoelectron_escape_flux_m2_s, iterations, residual, secondary_share=0.0, secondary_budget_residual_a_m2=0.0, top_sheath_field_v_m=None, top_cell_mean_field_v_m=None)

One accepted quasistatic matching-plane coupling receipt.

パラメータ:

• displacement_c_m2 (float)

• phi_v (float)

• electron_inward_flux_m2_s (float)

• ion_inward_flux_m2_s (float)

• electron_access_potential_v (float)

• ion_access_potential_v (float)

• photoelectron_barrier_potential_v (float)

• photoelectron_outward_flux_m2_s (float)

• photoelectron_mean_normal_energy_ev (float)

• electron_outward_flux_m2_s (float)

• ion_outward_flux_m2_s (float)

• photoelectron_return_flux_m2_s (float)

• photoelectron_escape_flux_m2_s (float)

• iterations (int)

• residual (float)

• secondary_share (float)

• secondary_budget_residual_a_m2 (float)

• top_sheath_field_v_m (float | None)

• top_cell_mean_field_v_m (float | None)

secondary_budget_residual_a_m2: float = 0.0

secondary_share: float = 0.0

top_cell_mean_field_v_m: float | None = None

top_sheath_field_v_m: float | None = None

displacement_c_m2: float

phi_v: float

electron_inward_flux_m2_s: float

ion_inward_flux_m2_s: float

electron_access_potential_v: float

ion_access_potential_v: float

photoelectron_barrier_potential_v: float

photoelectron_outward_flux_m2_s: float

photoelectron_mean_normal_energy_ev: float

electron_outward_flux_m2_s: float

ion_outward_flux_m2_s: float

photoelectron_return_flux_m2_s: float

photoelectron_escape_flux_m2_s: float

iterations: int

residual: float

class beach.MeshSelection(directory, mesh_ids, elem_indices, triangles, charges, step=None)

Selection of one or more meshes extracted from one run.

変数:

• directory (pathlib.Path) -- Output directory this selection belongs to.

• mesh_ids (tuple of int) -- Mesh identifiers included in this selection.

• elem_indices (numpy.ndarray) -- Original element indices in the full mesh arrays.

• triangles (numpy.ndarray) -- Selected triangle coordinates with shape (n_elem, 3, 3).

• charges (numpy.ndarray) -- Selected per-element charges with shape (n_elem,).

• step (int or None, default None) -- History batch step used for the charge snapshot.

パラメータ:

• directory (Path)

• mesh_ids (tuple[int, ...])

• elem_indices (ndarray)

• triangles (ndarray)

• charges (ndarray)

• step (int | None)

step: int | None = None

directory: Path

mesh_ids: tuple[int, ...]

elem_indices: ndarray

triangles: ndarray

charges: ndarray

class beach.MeshSource(mesh_id, source_kind, template_kind, elem_count, surface_model='insulator', epsilon_r=1.0)

Metadata for one source mesh record.

変数:

• mesh_id (int) -- Mesh identifier written in mesh_sources.csv.

• source_kind (str) -- Mesh source category (for example "template" or "obj").

• template_kind (str) -- Template subtype when source_kind is "template".

• elem_count (int) -- Number of triangle elements belonging to the mesh.

• surface_model (str) -- Surface response model for this mesh group.

• epsilon_r (float) -- Relative permittivity associated with this mesh group.

パラメータ:

• mesh_id (int)

• source_kind (str)

• template_kind (str)

• elem_count (int)

• surface_model (str)

• epsilon_r (float)

epsilon_r: float = 1.0

surface_model: str = 'insulator'

mesh_id: int

source_kind: str

template_kind: str

elem_count: int

class beach.PotentialSlice2D(plane, axis_u, axis_v, fixed_axis, fixed_value_m, u_values_m, v_values_m, potential_V)

Electric potential sampled on one axis-aligned 2D slice.

変数:

• plane (str) -- Plane name ("xy", "yz", or "xz").

• axis_u (str) -- First in-plane axis label.

• axis_v (str) -- Second in-plane axis label.

• fixed_axis (str) -- Axis held constant for the slice.

• fixed_value_m (float) -- Fixed-axis coordinate in meters.

• u_values_m (numpy.ndarray) -- Sample coordinates along axis_u.

• v_values_m (numpy.ndarray) -- Sample coordinates along axis_v.

• potential_V (numpy.ndarray) -- Potential grid in volts with shape (n_v, n_u).

パラメータ:

• plane (str)

• axis_u (str)

• axis_v (str)

• fixed_axis (str)

• fixed_value_m (float)

• u_values_m (ndarray)

• v_values_m (ndarray)

• potential_V (ndarray)

plane: str

axis_u: str

axis_v: str

fixed_axis: str

fixed_value_m: float

u_values_m: ndarray

v_values_m: ndarray

potential_V: ndarray

class beach.SecondaryEmissionHistoryEntry(batch, incident_species, hits, emitted_count, emitted_charge_c, mean_yield, generation_capped_count)

Rank-summed SEE diagnostics for one incident species and accepted batch.

パラメータ:

• batch (int)

• incident_species (str)

• hits (int)

• emitted_count (int)

• emitted_charge_c (float)

• mean_yield (float)

• generation_capped_count (int)

batch: int

incident_species: str

hits: int

emitted_count: int

emitted_charge_c: float

mean_yield: float

generation_capped_count: int

class beach.FieldKernel(source_triangles, source_charges, *, options=None, library_path=None)

Thin Python wrapper around libbeach_field_kernel.

The kernel uses the same Fortran FMM core as the simulator. Source geometry is fixed after build; charges can be refreshed cheaply with update_charges(). A cached_kneq0 periodic plan evaluates only the nonzero in-plane Fourier component; it is not the simulator's total field unless the physical zero mode and prescribed-field contribution are composed separately. When the saved upper Fourier switch is active, the simulator evaluates near H with Fourier sums; this FMM kernel does not reproduce those evaluations.

パラメータ:

• source_triangles (np.ndarray)

• source_charges (np.ndarray)

• options (FieldKernelOptions | None)

• library_path (str | Path | None)

build(source_triangles, *, options=None)

Build or rebuild a constant-density triangle-panel plan.

パラメータ:

• source_triangles (ndarray)

• options (FieldKernelOptions | None)

戻り値の型:

None

close()

Release the Fortran kernel handle.

戻り値の型:

None

property closed: bool

Whether close() has released the native handle.

diagnostics()

Return periodic operator-cache diagnostics for this built plan.

戻り値の型:

FieldKernelDiagnostics

eval_e(points)

Evaluate electric field vectors at points with shape (n, 3).

For cached_kneq0, this returns the k!=0 component only.

パラメータ:

points (ndarray)

戻り値の型:

ndarray

eval_e_direct(points)

Evaluate the exact non-periodic all-source electric field.

パラメータ:

points (ndarray)

戻り値の型:

ndarray

eval_phi(points)

Evaluate electric potential at points with shape (n, 3).

For cached_kneq0, this returns the k!=0 component only.

パラメータ:

points (ndarray)

戻り値の型:

ndarray

eval_phi_direct(points)

Evaluate the exact non-periodic all-source electric potential.

パラメータ:

points (ndarray)

戻り値の型:

ndarray

force_on_charges(positions, charges, *, origin=(0.0, 0.0, 0.0))

Return net force and torque on target charges in the current field.

For cached_kneq0, the current field is the k!=0 component only.

パラメータ:

• positions (ndarray)

• charges (ndarray)

• origin (Iterable[float])

戻り値の型:

tuple[ndarray, ndarray]

static is_available(library_path=None)

Return whether the shared kernel library can be loaded.

パラメータ:

library_path (str | Path | None)

戻り値の型:

bool

property options: FieldKernelOptions

Options of the currently built plan.

property source_charges: ndarray

Copy of the current source charges, one per source triangle.

update_charges(source_charges)

Refresh source charges without rebuilding source geometry.

パラメータ:

source_charges (ndarray)

戻り値の型:

None

class beach.FieldKernelBuildInfo(schema_version, version, version_mode, source_commit, build_id)

Source identity embedded in a BEACH field-kernel library.

パラメータ:

• schema_version (int)

• version (str)

• version_mode (str)

• source_commit (str)

• build_id (str)

schema_version: int

version: str

version_mode: str

source_commit: str

build_id: str

class beach.FieldKernelDiagnostics(periodic_cache_hit, periodic_operator_build_count, periodic_cache_fingerprint, periodic_cache_path)

Periodic operator-cache diagnostics for a built field kernel.

パラメータ:

• periodic_cache_hit (bool | None)

• periodic_operator_build_count (int)

• periodic_cache_fingerprint (str | None)

• periodic_cache_path (Path | None)

periodic_cache_hit: bool | None

periodic_operator_build_count: int

periodic_cache_fingerprint: str | None

periodic_cache_path: Path | None

exception beach.FieldKernelError

Raised when the shared field kernel cannot be used.

class beach.FieldKernelOptions(theta=0.5, leaf_max=16, order=4, periodic2=None, box_min=None, box_max=None, external_e0=(0.0, 0.0, 0.0), periodic_cache_dir=None, periodic_generation_tolerance=1e-08, resolved_field_solver='fmm')

Options passed to the native Fortran triangle-panel kernel.

パラメータ:

• theta (float)

• leaf_max (int)

• order (int)

• periodic2 (Mapping[str, object] | tuple[tuple[int, int], tuple[float, float], tuple[float, float], int, str, float, int] | Periodic2Config | None)

• box_min (tuple[float, float, float] | None)

• box_max (tuple[float, float, float] | None)

• external_e0 (tuple[float, float, float])

• periodic_cache_dir (str | None)

• periodic_generation_tolerance (float)

• resolved_field_solver (str)

box_max: tuple[float, float, float] | None = None

box_min: tuple[float, float, float] | None = None

external_e0: tuple[float, float, float] = (0.0, 0.0, 0.0)

leaf_max: int = 16

order: int = 4

periodic2: Mapping[str, object] | tuple[tuple[int, int], tuple[float, float], tuple[float, float], int, str, float, int] | Periodic2Config | None = None

periodic_cache_dir: str | None = None

periodic_generation_tolerance: float = 1e-08

resolved_field_solver: str = 'fmm'

theta: float = 0.5

beach.field_kernel_build_info(library_path=None)

Read and validate build-origin metadata from a field-kernel library.

パラメータ:

library_path (str | Path | None)

戻り値の型:

FieldKernelBuildInfo

class beach.PeriodicZeroMode(source_heights_m, source_charges_C, area_xy_m2, *, e_bottom_V_m=0.0, z_gauge_m=None, phi_gauge_V=0.0, library_path=None)

Evaluate the simulator's physical x/y-periodic zero mode.

source_heights_m stores the three vertex heights for each triangle source.

パラメータ:

• source_heights_m (np.ndarray)

• source_charges_C (np.ndarray)

• area_xy_m2 (float)

• e_bottom_V_m (float)

• z_gauge_m (float | None)

• phi_gauge_V (float)

• library_path (str | Path | None)

close()

Release the native handle. Repeated calls are harmless.

戻り値の型:

None

eval(z_m, trace='principal_value')

Return native potential and vertical field at the requested heights.

パラメータ:

• z_m (ndarray | float)

• trace (str)

戻り値の型:

tuple[ndarray, ndarray]

update_charges(source_charges_C, *, e_bottom_V_m=None)

Refresh source charges without rebuilding the height plan.

e_bottom_V_m overrides the constructor value for this update only. Omitting it preserves the historical fixed-bottom-field behavior.

パラメータ:

• source_charges_C (ndarray)

• e_bottom_V_m (float | None)

戻り値の型:

None

beach.calc_coulomb(result, target, source, *, step=-1, torque_origin='target_center', periodic2=None, quadrature_order=7, config_path=None, library_path=None, kernel=None)

Compute force/torque on one panel group from another panel group (heavy: native kernel).

パラメータ:

• result (RunResult, RunContext, or Beach) -- Run to evaluate.

• target (int, MeshSelection, or iterable of those) -- Disjoint mesh groups; the force acts on target (group A).

• source (int, MeshSelection, or iterable of those) -- Disjoint mesh groups; the force acts on target (group A).

• step (int or None, default -1) -- History step whose charges are used. None uses charges.csv.

• torque_origin ({"target_center", "source_center", "origin"}, default "target_center") -- Torque reference point ("group_a_center" / "group_b_center" alias the first two).

• periodic2 (mapping or None, default None) -- Two-axis periodic setting. None resolves it from the run.

• quadrature_order (int, default 7) -- Gauss-Duffy order of the target-panel quadrature.

• config_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• library_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• kernel (FieldKernel or None, default None) -- Open kernel built from this run's full mesh, for example Beach.kernel(). During the call its source charges are those of source alone, and they are restored afterwards; it is not closed. Its plan is used as given, so periodic2 and library_path do not apply, and its uniform external field is excluded from the result. The full-mesh plan agrees with the default source-only plan to FMM accuracy. None builds a source-only kernel for this call and closes it.

戻り値:

Force and torque on both groups.

戻り値の型:

CoulombInteraction

class beach.AdhesionProfile(kind, displacement_m=<factory>, force_values_N=<factory>, constant_force_N=0.0, range_m=0.0)

Finite-range object-level resisting force and its exact work.

パラメータ:

• kind (str)

• displacement_m (ndarray)

• force_values_N (ndarray)

• constant_force_N (float)

• range_m (float)

property breakpoints_m: ndarray

constant_force_N: float = 0.0

classmethod finite_range_constant(force_N, range_m)

パラメータ:

• force_N (float)

• range_m (float)

戻り値の型:

AdhesionProfile

force_N(displacement_m)

パラメータ:

displacement_m (ndarray | float)

戻り値の型:

ndarray | float

classmethod none()

戻り値の型:

AdhesionProfile

range_m: float = 0.0

classmethod tabulated(displacement_m, force_N)

パラメータ:

• displacement_m (ndarray | list[float])

• force_N (ndarray | list[float])

戻り値の型:

AdhesionProfile

work_J(displacement_m)

パラメータ:

displacement_m (ndarray | float)

戻り値の型:

ndarray | float

kind: str

displacement_m: ndarray

force_values_N: ndarray

class beach.DetachmentResult(*, mass_kg, gravity_m_s2, eta_translation, energy_tolerance_J, displacement_m, electrostatic_work_J, gravity_work_J, adhesion_work_J, dissipation_work_J, gravity_corrected_work_J, available_energy_J, electrostatic_only_speed_m_s, gravity_corrected_speed_m_s, speed_m_s, minimum_available_energy_J, barrier_free_from_rest, first_inaccessible_displacement_m, endpoint_available_energy_J, endpoint_positive, endpoint_reachable_from_rest, endpoint_speed_m_s, maximum_reachable_speed_m_s, instantaneous_force_margin_N, source_path_status, numerically_qualified)

Work, speed, and continuous barrier diagnostics for one force path.

パラメータ:

• mass_kg (float)

• gravity_m_s2 (float)

• eta_translation (float)

• energy_tolerance_J (float)

• displacement_m (ndarray)

• electrostatic_work_J (ndarray)

• gravity_work_J (ndarray)

• adhesion_work_J (ndarray)

• dissipation_work_J (ndarray)

• gravity_corrected_work_J (ndarray)

• available_energy_J (ndarray)

• electrostatic_only_speed_m_s (ndarray)

• gravity_corrected_speed_m_s (ndarray)

• speed_m_s (ndarray)

• minimum_available_energy_J (float)

• barrier_free_from_rest (bool)

• first_inaccessible_displacement_m (float | None)

• endpoint_available_energy_J (float)

• endpoint_positive (bool)

• endpoint_reachable_from_rest (bool)

• endpoint_speed_m_s (float)

• maximum_reachable_speed_m_s (float)

• instantaneous_force_margin_N (float)

• source_path_status (str)

• numerically_qualified (bool)

mass_kg: float

gravity_m_s2: float

eta_translation: float

energy_tolerance_J: float

displacement_m: ndarray

electrostatic_work_J: ndarray

gravity_work_J: ndarray

adhesion_work_J: ndarray

dissipation_work_J: ndarray

gravity_corrected_work_J: ndarray

available_energy_J: ndarray

electrostatic_only_speed_m_s: ndarray

gravity_corrected_speed_m_s: ndarray

speed_m_s: ndarray

minimum_available_energy_J: float

barrier_free_from_rest: bool

first_inaccessible_displacement_m: float | None

endpoint_available_energy_J: float

endpoint_positive: bool

endpoint_reachable_from_rest: bool

endpoint_speed_m_s: float

maximum_reachable_speed_m_s: float

instantaneous_force_margin_N: float

source_path_status: str

numerically_qualified: bool

class beach.ObjectForcePath(*, displacement_m, force_N, torque_Nm, electrostatic_work_J, potential_energy_J=None, potential_difference_work_J=None, component_force_N=<factory>, component_torque_Nm=<factory>, numerical_metadata=<factory>, status='converged', refinement_count=0, work_relative_mismatch=None, work_absolute_mismatch_J=None)

Force and torque samples for a rigid object displacement path.

パラメータ:

• displacement_m (ndarray)

• force_N (ndarray)

• torque_Nm (ndarray)

• electrostatic_work_J (ndarray)

• potential_energy_J (ndarray | None)

• potential_difference_work_J (ndarray | None)

• component_force_N (Mapping[str, ndarray])

• component_torque_Nm (Mapping[str, ndarray])

• numerical_metadata (Mapping[str, object])

• status (str)

• refinement_count (int)

• work_relative_mismatch (float | None)

• work_absolute_mismatch_J (float | None)

evaluate_release(mass_kg, gravity_m_s2, adhesion, eta_translation=1.0, energy_tolerance_J=1e-18, dissipation_work_J=None)

Evaluate from-rest accessibility for the continuous piecewise path.

パラメータ:

• mass_kg (float)

• gravity_m_s2 (float)

• adhesion (AdhesionProfile)

• eta_translation (float)

• energy_tolerance_J (float)

• dissipation_work_J (ndarray | None)

戻り値の型:

DetachmentResult

classmethod from_samples(displacement_m, force_N, torque_Nm, potential_energy_J=None)

パラメータ:

• displacement_m (ndarray)

• force_N (ndarray)

• torque_Nm (ndarray)

• potential_energy_J (ndarray | None)

戻り値の型:

ObjectForcePath

potential_difference_work_J: ndarray | None = None

potential_energy_J: ndarray | None = None

refinement_count: int = 0

status: str = 'converged'

work_absolute_mismatch_J: float | None = None

work_relative_mismatch: float | None = None

displacement_m: ndarray

force_N: ndarray

torque_Nm: ndarray

electrostatic_work_J: ndarray

component_force_N: Mapping[str, ndarray]

component_torque_Nm: Mapping[str, ndarray]

numerical_metadata: Mapping[str, object]

class beach.ObjectWrench(*, mesh_id, step, total_charge_C, force_N, torque_Nm, torque_origin_m, transform=None, transform_origin_m=None, components=<factory>, numerical_metadata=<factory>)

Immutable object-level force, torque, and component decomposition.

パラメータ:

• mesh_id (int)

• step (int | None)

• total_charge_C (float)

• force_N (ndarray)

• torque_Nm (ndarray)

• torque_origin_m (ndarray)

• transform (object | None)

• transform_origin_m (ndarray | None)

• components (Mapping[str, WrenchComponent])

• numerical_metadata (Mapping[str, object])

transform: object | None = None

transform_origin_m: ndarray | None = None

mesh_id: int

step: int | None

total_charge_C: float

force_N: ndarray

torque_Nm: ndarray

torque_origin_m: ndarray

components: Mapping[str, WrenchComponent]

numerical_metadata: Mapping[str, object]

class beach.WrenchComponent(force_N, torque_Nm, potential_energy_J=None)

One physical contribution to an object force and torque.

パラメータ:

• force_N (ndarray)

• torque_Nm (ndarray)

• potential_energy_J (float | None)

potential_energy_J: float | None = None

force_N: ndarray

torque_Nm: ndarray

class beach.KernelObjectForceRecord(mesh_id, step, total_charge_C, center_m, force_N, torque_Nm)

Object-level net force/torque computed by the Fortran field kernel.

パラメータ:

• mesh_id (int)

• step (int | None)

• total_charge_C (float)

• center_m (ndarray)

• force_N (ndarray)

• torque_Nm (ndarray)

mesh_id: int

step: int | None

total_charge_C: float

center_m: ndarray

force_N: ndarray

torque_Nm: ndarray

beach.calc_object_forces_kernel(result, *, step=-1, target_mesh_ids=None, periodic2=None, theta=None, leaf_max=None, order=None, config_path=None, library_path=None, kernel=None)

Compute object-wise net force with the native field kernel (heavy).

For each target object, its own source charges are zeroed before evaluating the target panel lattice is integrated with seventh-order Gauss-Duffy quadrature. A configured uniform sim.e0 is added to the target field, matching the simulator pusher semantics while avoiding central-cell primary self-force contamination.

kernel is an open kernel built from this run, for example Beach.kernel(). Its plan is used as given, so periodic2, theta, leaf_max, order, and library_path do not apply; its source charges are replaced by the step charges during the call and restored afterwards, and it is not closed. None builds a kernel for this call and closes it.

パラメータ:

• result (RunResult | object)

• step (int | None)

• target_mesh_ids (int | Iterable[int] | None)

• periodic2 (Mapping[str, object] | None)

• theta (float | None)

• leaf_max (int | None)

• order (int | None)

• config_path (str | Path | None)

• library_path (str | Path | None)

• kernel (FieldKernel | None)

戻り値の型:

tuple[KernelObjectForceRecord, ...]

beach.field_kernel_options_from_result(result, *, periodic2=None, theta=None, leaf_max=None, order=None, config_path=None)

Resolve field-kernel options from a BEACH result and optional config (light).

パラメータ:

• result (RunResult | object)

• periodic2 (Mapping[str, object] | None)

• theta (float | None)

• leaf_max (int | None)

• order (int | None)

• config_path (str | Path | None)

戻り値の型:

FieldKernelOptions

beach.compute_electric_field_points(result, points, *, chunk_size=2048, periodic2=None, config_path=None, library_path=None, kernel=None)

Evaluate the triangle-P0 electric field at arbitrary points (heavy: native kernel).

パラメータ:

• result (RunResult, RunContext, or Beach) -- Run to evaluate.

• points (numpy.ndarray) -- Sampling points with shape (n_points, 3) in meters.

• chunk_size (int, default 2048) -- Number of points evaluated per kernel call.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting. None resolves it from the run.

• config_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• library_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• kernel (FieldKernel or None, default None) -- Open kernel built from this run, for example Beach.kernel(). It is evaluated with its own plan and charges and is not closed; periodic2 and library_path then do not apply. None builds a kernel for this call (latest history charges) and closes it.

戻り値:

Electric field in V/m with shape (n_points, 3).

戻り値の型:

numpy.ndarray

beach.trace_field_lines(result, seed_points, *, ds=None, max_steps=500, periodic2=None, direction='both', box_min=None, box_max=None, config_path=None, library_path=None, kernel=None)

Trace field lines with RK4 on the triangle-P0 field (heavy: native kernel).

パラメータ:

• result (RunResult, RunContext, or Beach) -- Run to evaluate.

• seed_points (numpy.ndarray) -- Starting points with shape (n_seeds, 3) in meters.

• ds (float or None, default None) -- Step length in meters. None uses half the mean mesh edge length.

• max_steps (int, default 500) -- Maximum steps per direction.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting. None resolves it from the run.

• direction ({"both", "forward", "backward"}, default "both") -- Trace along the field, against it, or both.

• box_min (iterable of float or None, default None) -- Box that stops a line when it is left.

• box_max (iterable of float or None, default None) -- Box that stops a line when it is left.

• config_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• library_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• kernel (FieldKernel or None, default None) -- Open kernel built from this run, for example Beach.kernel(). It is evaluated with its own plan and charges and is not closed; periodic2 and library_path then do not apply. None builds a kernel for this call (latest history charges) and closes it.

戻り値:

One (n_points_i, 3) polyline per seed.

戻り値の型:

list of numpy.ndarray

beach.analyze_coulomb_mobility(result, *, step=-1, config_path=None, library_path=None, gravity=(0.0, 0.0, -9.81), support_normal=None, support_kinds=('plane',), target_kinds=None, density_kg_m3=None, mu_static=None, mu_roll=None, adhesion_force_N=0.0)

Analyze per-object Coulomb mobility indicators (heavy: native kernel per object).

パラメータ:

• result (RunResult or Beach-like object) -- Run result or object exposing result as RunResult.

• step (int or None, default -1) -- History batch step used for charge snapshot. None uses final charges from charges.csv.

• config_path (str, pathlib.Path, or None, default None) -- Optional beach.toml path used for object labels and geometry metadata.

• gravity (iterable of float, default (0, 0, -9.81)) -- Gravity vector in meters per second squared.

• support_normal (iterable of float or None, default None) -- Support-normal direction. None uses -gravity when possible, otherwise +z.

• support_kinds (iterable of str or None, default ("plane",)) -- Object kinds treated as fixed supports and excluded from default targets.

• target_kinds (iterable of str or None, default None) -- Explicit target kinds to analyze. None means all non-support objects, falling back to all objects when no non-support object exists.

• density_kg_m3 (float or None, default None) -- Bulk density used to estimate weight for volumetric templates.

• mu_static (float or None, default None) -- Static-friction coefficient for slide-ratio estimation.

• mu_roll (float or None, default None) -- Rolling-resistance coefficient for roll-ratio estimation.

• adhesion_force_N (float, default 0.0) -- Additional normal adhesion resisting lift.

• library_path (str | Path | None)

戻り値:

Per-object force/torque summary and mobility indicators.

戻り値の型:

CoulombMobilityAnalysis

例外:

ValueError -- If arguments are invalid or no target objects are available.

class beach.ObjectInteractionSnapshot(*, result, step, triangles_m, centers_m, charges_C, mesh_ids, options, periodic_model, periodic, zero_mode, external_e0_V_m, library_path, zero_mode_lower_boundary=None, zero_mode_area_xy_m2=None)

Immutable source geometry and charge state for object-level probes.

パラメータ:

• result (RunResult)

• step (int | None)

• triangles_m (np.ndarray)

• centers_m (np.ndarray)

• charges_C (np.ndarray)

• mesh_ids (np.ndarray)

• options (FieldKernelOptions)

• periodic_model (str)

• periodic (FieldKernel)

• zero_mode (PeriodicZeroMode | None)

• external_e0_V_m (np.ndarray)

• library_path (str | Path | None)

• zero_mode_lower_boundary (str | None)

• zero_mode_area_xy_m2 (float | None)

close()

Close probes and native source evaluators.

戻り値の型:

None

classmethod from_result(result, *, step=-1, config_path=None, periodic_model='configured', cache_dir=None, generation_tolerance=None, library_path=None)

Build one source snapshot from saved BEACH geometry and charges (heavy: native kernels).

パラメータ:

• result (RunResult | object)

• step (int | None)

• config_path (str | Path | None)

• periodic_model (str)

• cache_dir (str | Path | None)

• generation_tolerance (float | None)

• library_path (str | Path | None)

戻り値の型:

ObjectInteractionSnapshot

object_probe(mesh_id, *, self_policy='exclude_primary_keep_images', target_integration='auto', quadrature_order=7)

Create one independently movable target probe.

パラメータ:

• mesh_id (int)

• self_policy (str)

• target_integration (str)

• quadrature_order (int)

戻り値の型:

ObjectProbe

property source_charges_C: ndarray

property source_positions_m: ndarray

property source_triangles_m: ndarray

Return immutable saved panels used by the all-source field kernel.

class beach.ObjectProbe(*, snapshot, mesh_id, target_mask, target_integration, quadrature_order)

Selected object charge distribution movable within a frozen snapshot.

パラメータ:

• snapshot (ObjectInteractionSnapshot)

• mesh_id (int)

• target_mask (np.ndarray)

• target_integration (str)

• quadrature_order (int)

close()

戻り値の型:

None

property geometric_area_centroid_m: ndarray

Return the immutable area-weighted centroid used by named origins.

property target_geometry_representation: str

Return how the selected target mesh is represented for mechanics.

property target_triangles_m: ndarray

Return the immutable target panels in their connected geometry branch.

property vertex_bounding_center_m: ndarray

Return the immutable center of the target vertex axis-aligned bounds.

property vertex_bounding_radius_m: float

Return the largest target-vertex distance from vertex_bounding_center_m.

vertical_path(displacement_m, *, adaptive=True, relative_tolerance=0.005, force_absolute_tolerance_N=1e-12, work_absolute_tolerance_J=1e-18, max_refinement=8, torque_origin='geometric_area_centroid', components=True)

Evaluate a frozen-source vertical translation path.

パラメータ:

• displacement_m (ndarray)

• adaptive (bool)

• relative_tolerance (float)

• force_absolute_tolerance_N (float)

• work_absolute_tolerance_J (float)

• max_refinement (int)

• torque_origin (str | Iterable[float])

• components (bool)

戻り値の型:

ObjectForcePath

wrench(transform=None, transform_origin='geometric_area_centroid', torque_origin='geometric_area_centroid', components=True)

Evaluate force and torque with primary-only self exclusion.

パラメータ:

• transform (RigidTransform | None)

• transform_origin (str | Iterable[float])

• torque_origin (str | Iterable[float])

• components (bool)

戻り値の型:

ObjectWrench

class beach.FiniteShellConvergenceResult(*, image_layers, symmetric_paths, corrected_paths, force_increment_error_N, work_increment_error_J, increment_converged, status, selected_image_layers, selected_path, force_tail_proxy_N=None, work_tail_proxy_J=None, reference_force_error_N=None, reference_work_error_J=None, reference_converged=None, reference_model=None)

Two-successive combined-gate convergence record for finite shells.

パラメータ:

• image_layers (ndarray)

• symmetric_paths (tuple[ObjectForcePath, ...])

• corrected_paths (tuple[ObjectForcePath, ...])

• force_increment_error_N (ndarray)

• work_increment_error_J (ndarray)

• increment_converged (ndarray)

• status (str)

• selected_image_layers (int | None)

• selected_path (ObjectForcePath | None)

• force_tail_proxy_N (ndarray | None)

• work_tail_proxy_J (ndarray | None)

• reference_force_error_N (ndarray | None)

• reference_work_error_J (ndarray | None)

• reference_converged (ndarray | None)

• reference_model (str | None)

force_tail_proxy_N: ndarray | None = None

reference_converged: ndarray | None = None

reference_force_error_N: ndarray | None = None

reference_model: str | None = None

reference_work_error_J: ndarray | None = None

work_tail_proxy_J: ndarray | None = None

image_layers: ndarray

symmetric_paths: tuple[ObjectForcePath, ...]

corrected_paths: tuple[ObjectForcePath, ...]

force_increment_error_N: ndarray

work_increment_error_J: ndarray

increment_converged: ndarray

status: str

selected_image_layers: int | None

selected_path: ObjectForcePath | None

class beach.FiniteShellWrenchResult(*, image_layers, closure_shift_V_m, symmetric, e_bottom_zero, selected, selected_closure)

Raw and closure-corrected wrenches for one finite image shell.

パラメータ:

• image_layers (int)

• closure_shift_V_m (ndarray)

• symmetric (ObjectWrench)

• e_bottom_zero (ObjectWrench)

• selected (ObjectWrench)

• selected_closure (str)

image_layers: int

closure_shift_V_m: ndarray

symmetric: ObjectWrench

e_bottom_zero: ObjectWrench

selected: ObjectWrench

selected_closure: str

beach.finite_shell_convergence(snapshot, probe, displacement_m, *, max_layers=12, relative_tolerance=0.01, force_floor_N=1e-12, work_floor_J=1e-18)

Increase shells until two tail/reference combined gates converge (heavy).

パラメータ:

• snapshot (ObjectInteractionSnapshot)

• probe (ObjectProbe)

• displacement_m (ndarray)

• max_layers (int)

• relative_tolerance (float)

• force_floor_N (float)

• work_floor_J (float)

戻り値の型:

FiniteShellConvergenceResult

beach.finite_shell_wrench(snapshot, probe, transform, image_layers, closure, *, torque_origin='geometric_area_centroid', components=True)

Evaluate one native finite shell with both explicit zero-mode closures (heavy).

パラメータ:

• snapshot (ObjectInteractionSnapshot)

• probe (ObjectProbe)

• transform (RigidTransform | None)

• image_layers (int)

• closure (str)

• torque_origin (str | Iterable[float])

• components (bool)

戻り値の型:

FiniteShellWrenchResult

beach.compute_potential_mesh(result, *, periodic2=None, reference_point=None, config_path=None, library_path=None, source='auto', kernel=None)

Evaluate triangle-P0 potential at every panel centroid (heavy unless saved values are used).

パラメータ:

• result (RunResult, RunContext, or Beach) -- Run to evaluate.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting. None resolves it from the run.

• reference_point (iterable of float, {"species1_injection_center"}, or None, default None) -- Point whose potential is subtracted. None returns absolute potential.

• config_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• library_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• source ({"auto", "saved", "kernel"}, default "auto") -- "saved" returns the simulator's mesh_potential.csv (light) and rejects periodic2, reference_point, and kernel. "kernel" always evaluates the native kernel (heavy). "auto" uses the saved values when they exist and none of periodic2, reference_point, or kernel is given, and the kernel otherwise.

• kernel (FieldKernel or None, default None) -- Open kernel built from this run, for example Beach.kernel(step=None). It is evaluated with its own plan and charges and is not closed; periodic2 and library_path then do not apply. None builds a kernel for this call and closes it.

戻り値:

Potential in volts with shape (mesh_nelem,).

戻り値の型:

numpy.ndarray

beach.compute_potential_points(result, points, *, chunk_size=2048, periodic2=None, reference_point=None, config_path=None, library_path=None, kernel=None)

Evaluate triangle-P0 potential at arbitrary points (heavy: native kernel).

パラメータ:

• result (RunResult, RunContext, or Beach) -- Run to evaluate.

• points (numpy.ndarray) -- Sampling points with shape (n_points, 3) in meters.

• chunk_size (int, default 2048) -- Number of points evaluated per kernel call.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting. None resolves it from the run.

• reference_point (iterable of float, {"species1_injection_center"}, or None, default None) -- Point whose potential is subtracted. None returns absolute potential.

• config_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• library_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• kernel (FieldKernel or None, default None) -- Open kernel built from this run, for example Beach.kernel(step=None). It is evaluated with its own plan and charges and is not closed; periodic2 and library_path then do not apply. None builds a kernel for this call and closes it.

戻り値:

Potential in volts with shape (n_points,).

戻り値の型:

numpy.ndarray

beach.compute_potential_slices(result, *, box_min, box_max, grid_n=200, xy_z=None, yz_x=None, xz_y=None, chunk_size=2048, periodic2=None, reference_point=None, config_path=None, library_path=None, kernel=None)

Sample triangle-P0 potential on XY, YZ, and XZ slices (heavy: native kernel).

The planes cross box_min-box_max at xy_z, yz_x, and xz_y (box center when None) on a grid_n x grid_n grid. The other arguments, including kernel, are those of compute_potential_points().

パラメータ:

• result (RunResult | object)

• box_min (Iterable[float])

• box_max (Iterable[float])

• grid_n (int)

• xy_z (float | None)

• yz_x (float | None)

• xz_y (float | None)

• chunk_size (int)

• periodic2 (Mapping[str, object] | None)

• reference_point (Iterable[float] | str | None)

• config_path (str | Path | None)

• library_path (str | Path | None)

• kernel (FieldKernel | None)

戻り値の型:

dict[str, PotentialSlice2D]

class beach.BeachScene(result, step, centers_m, triangles_m, charges_C, mesh_ids, config_path=None, transform_backend='numpy', library_path=None)

Editable what-if view of one BEACH charge snapshot.

Geometry edits are immutable: move/rotate return a new scene, keeping charges attached to their original mesh elements.

パラメータ:

• result (RunResult)

• step (int | None)

• centers_m (ndarray)

• triangles_m (ndarray)

• charges_C (ndarray)

• mesh_ids (ndarray)

• config_path (Path | None)

• transform_backend (Literal['numpy', 'numba', 'auto'])

• library_path (Path | None)

calc_object_forces_kernel(*, target_mesh_ids=None, periodic2=None, theta=None, leaf_max=None, order=None, config_path=None, library_path=None)

Compute object-wise force/torque for the edited scene geometry (heavy: native kernel).

パラメータ:

• target_mesh_ids (int | Iterable[int] | None)

• periodic2 (Mapping[str, object] | None)

• theta (float | None)

• leaf_max (int | None)

• order (int | None)

• config_path (str | Path | None)

• library_path (str | Path | None)

戻り値の型:

tuple[KernelObjectForceRecord, ...]

property centers: ndarray

Alias for element centers in meters.

property charges: ndarray

Alias for per-element charges in coulombs.

config_path: Path | None = None

field_kernel(*, periodic2=None, theta=None, leaf_max=None, order=None, config_path=None, library_path=None)

Build a native field kernel for the edited scene geometry (heavy).

パラメータ:

• periodic2 (Mapping[str, object] | None)

• theta (float | None)

• leaf_max (int | None)

• order (int | None)

• config_path (str | Path | None)

• library_path (str | Path | None)

戻り値の型:

beach.native.kernel.FieldKernel

classmethod from_result(result, *, step=-1, config_path=None, transform_backend='numpy', library_path=None)

Create a scene from a BEACH output snapshot (saved values only, light).

config_path and library_path become the defaults of the scene's kernel methods; a Beach result contributes its own config path.

パラメータ:

• result (RunResult | object)

• step (int | None)

• config_path (str | Path | None)

• transform_backend (Literal['numpy', 'numba', 'auto'])

• library_path (str | Path | None)

戻り値の型:

BeachScene

library_path: Path | None = None

move(mesh_ids, *, by)

Translate one or more objects by by meters.

パラメータ:

• mesh_ids (int | Iterable[int])

• by (Iterable[float])

戻り値の型:

BeachScene

object_center(mesh_ids)

Return the centroid of one or more objects.

パラメータ:

mesh_ids (int | Iterable[int])

戻り値の型:

ndarray

property object_ids: tuple[int, ...]

Return sorted mesh ids present in this scene.

rotate(mesh_ids, *, axis, angle_rad=None, angle_deg=None, origin='object_center')

Rotate one or more objects around an origin.

パラメータ:

• mesh_ids (int | Iterable[int])

• axis (Iterable[float])

• angle_rad (float | None)

• angle_deg (float | None)

• origin (Literal['object_center', 'origin'] | ~typing.Iterable[float])

戻り値の型:

BeachScene

transform(mesh_ids, transform, *, origin='object_center')

Apply a rigid transform to one or more objects.

パラメータ:

• mesh_ids (int | Iterable[int])

• transform (RigidTransform)

• origin (Literal['object_center', 'origin'] | ~typing.Iterable[float])

戻り値の型:

BeachScene

transform_backend: Literal['numpy', 'numba', 'auto'] = 'numpy'

property triangles: ndarray

Alias for triangle vertices in meters.

with_transform_backend(backend)

Return a scene using another point-transform backend.

パラメータ:

backend (Literal['numpy', 'numba', 'auto'])

戻り値の型:

BeachScene

result: RunResult

step: int | None

centers_m: ndarray

triangles_m: ndarray

charges_C: ndarray

mesh_ids: ndarray

class beach.RigidTransform(rotation, translation_m)

Rigid transform for row-major point arrays.

The transform is applied as origin + R @ (point - origin) + translation.

パラメータ:

• rotation (ndarray)

• translation_m (ndarray)

apply(points, *, origin=(0.0, 0.0, 0.0), backend='numpy')

Apply this transform to (..., 3) points.

パラメータ:

• points (ndarray)

• origin (Iterable[float])

• backend (Literal['numpy', 'numba', 'auto'])

戻り値の型:

ndarray

classmethod from_axis_angle(axis, *, angle_rad=None, angle_deg=None, translation_m=(0.0, 0.0, 0.0))

Build a transform from an axis-angle rotation.

パラメータ:

• axis (Iterable[float])

• angle_rad (float | None)

• angle_deg (float | None)

• translation_m (Iterable[float])

戻り値の型:

RigidTransform

classmethod identity()

Return an identity transform.

戻り値の型:

RigidTransform

classmethod translation(by)

Return a pure translation transform.

パラメータ:

by (Iterable[float])

戻り値の型:

RigidTransform

rotation: ndarray

translation_m: ndarray

beach.animate_history_mesh(result, output_path=None, *, quantity='charge', fps=10, frame_stride=1, total_frames=None, cmap=None, periodic2=None, apply_periodic2_mesh=False, periodic2_repeat=0, reference_point=None, view_elev=None, view_azim=None, library_path=None, kernel=None)

Render mesh history as an animation (heavy for quantity="potential").

パラメータ:

• result (RunResult or Beach-like object) -- Run result or object exposing result as RunResult.

• output_path (str or pathlib.Path or None, default None) -- Output GIF path. If None, return a live FuncAnimation object.

• quantity ({"charge", "potential"}, default "charge") -- Quantity used for per-face coloring.

• fps (int, default 10) -- Frames per second.

• frame_stride (int, default 1) -- Use every frame_stride-th snapshot.

• total_frames (int or None, default None) -- Evenly sampled frame count. Cannot be combined with frame_stride != 1.

• cmap (str or None, default None) -- Matplotlib colormap name. None uses quantity-specific defaults.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting for potential mode. None の場合は 出力ディレクトリ近傍の beach.toml から自動判定する。

• apply_periodic2_mesh (bool, default False) -- True の場合、triangle 重心を周期セルへ wrap する平行移動を各 face に 適用して描画する。

• periodic2_repeat (int, default 0) -- 周期イメージの複製数。n を指定すると各周期軸方向に -n から +n までの (2n+1)^2 コピーを生成して描画する。0 は複製なし。

• reference_point (iterable of float, {"species1_injection_center"}, or None, default None) -- 基準電位を差し引く参照点。None は絶対電位、"species1_injection_center" は species1 の注入面中心を基準にした電位差を描く。

• view_elev (float or None, default None) -- 3D view elevation angle in degrees. None uses the default (24.0).

• view_azim (float or None, default None) -- 3D view azimuth angle in degrees. None uses the default (-58.0).

• library_path (str, pathlib.Path, or None, default None) -- Native kernel library for potential mode.

• kernel (FieldKernel or None, default None) -- Open kernel built from this run that evaluates potential mode with its own plan; its source charges are stepped through the history frames and then restored, and it is not closed. periodic2 then only wraps and replicates the drawn mesh. None builds a kernel for potential mode.

戻り値:

Written GIF path when output_path is provided, otherwise animation object.

戻り値の型:

pathlib.Path or matplotlib.animation.FuncAnimation

例外:

ValueError -- If arguments are invalid or history/geometry data is unavailable.

beach.plot_mesh_source_boxplot(result, *, quantity='charge', step=-1, showfliers=True, config_path=None, library_path=None)

Plot area-weighted boxplots per mesh source (heavy for potential not saved in mesh_potential.csv).

パラメータ:

• result (RunResult or Beach-like object) -- Run result or object exposing result as RunResult.

• quantity ({"charge", "potential"}, default "charge") -- Quantity used in boxplot values.

• step (int or None, default -1) -- History batch step used for charge snapshot. None uses final charges from charges.csv.

• showfliers (bool, default True) -- Whether outlier markers are rendered.

• config_path (str | Path | None)

• library_path (str | Path | None)

戻り値:

(figure, axes) from matplotlib.

戻り値の型:

tuple

例外:

ValueError -- If triangle geometry is unavailable or plot arguments are invalid.

beach.plot_field_lines_3d(result, seed_points, *, ds=None, max_steps=500, periodic2=None, direction='both', box_min=None, box_max=None, show_mesh=True, mesh_alpha=0.25, mesh_cmap='coolwarm', line_color=None, line_cmap='plasma', line_width=1.2, view_elev=24.0, view_azim=-58.0, title='Electric field lines', figsize=(9, 7), config_path=None, library_path=None, kernel=None)

Plot triangle-P0 field lines and an optional surface mesh (heavy: native kernel).

The tracing arguments, including kernel, are those of beach.trace_field_lines(). show_mesh overlays the mesh colored by surface charge density with mesh_cmap and mesh_alpha; lines use line_color or, when it is None, line_cmap. Returns (figure, axes).

パラメータ:

• result (RunResult | object)

• seed_points (np.ndarray)

• ds (float | None)

• max_steps (int)

• periodic2 (Mapping[str, object] | None)

• direction (str)

• box_min (Iterable[float] | None)

• box_max (Iterable[float] | None)

• show_mesh (bool)

• mesh_alpha (float)

• mesh_cmap (str)

• line_color (str | None)

• line_cmap (str)

• line_width (float)

• view_elev (float)

• view_azim (float)

• title (str)

• figsize (tuple[float, float])

• config_path (str | Path | None)

• library_path (str | Path | None)

• kernel (FieldKernel | None)

戻り値の型:

tuple[Figure, Axes3D]

beach.plot_coulomb_force_matrix(result, *, step=-1, component='z', target_kinds=None, config_path=None, library_path=None, cmap='coolwarm', annotate=True, workers=1, kernel=None)

Plot an object-wise Coulomb-force matrix (heavy: native kernel).

パラメータ:

• result (RunResult or Beach-like object) -- Run result or object exposing result as RunResult.

• step (int or None, default -1) -- History batch step used for charge snapshot. None uses final charges from charges.csv.

• component ({"x", "y", "z"}, default "z") -- Force component rendered in the matrix.

• target_kinds (iterable of str or None, default None) -- Template kinds used as target objects. None means all objects.

• config_path (str, pathlib.Path, or None, default None) -- Optional beach.toml path used for object labels/order. None auto-detects near result.directory when possible.

• cmap (str, default "coolwarm") -- Matplotlib colormap name.

• annotate (bool, default True) -- Whether to draw scientific-notation values inside each cell.

• workers (int, default 1) -- Number of worker processes used for source/target force entries.

• kernel (FieldKernel or None, default None) -- Open full-mesh kernel built from this run, shared by every entry when workers == 1 (see beach.calc_coulomb()). Worker processes cannot share it, so with workers > 1 each entry builds its own kernel.

• library_path (str | Path | None)

戻り値:

(figure, axes) from matplotlib.

戻り値の型:

tuple

例外:

ValueError -- If no suitable objects are available or arguments are invalid.

beach.plot_charge_mesh(result, *, cmap='coolwarm', view_elev=24.0, view_azim=-58.0, periodic2=None, apply_periodic2_mesh=False, periodic2_mesh_mode='centroid', periodic2_repeat=0, axis_unit='m')

Plot a 3D mesh colored by surface charge density (light: saved values only).

パラメータ:

• result (RunResult or Beach-like object) -- Run result or object exposing result as RunResult.

• cmap (str, default "coolwarm") -- Matplotlib colormap name.

• view_elev (float, default 24.0) -- Elevation angle in degrees passed to Axes3D.view_init.

• view_azim (float, default -58.0) -- Azimuth angle in degrees passed to Axes3D.view_init.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting used when apply_periodic2_mesh=True. None の場合は出力ディレクトリ近傍の beach.toml から自動判定する。

• apply_periodic2_mesh (bool, default False) -- True の場合、triangle 重心を周期セルへ wrap する平行移動を各 face に 適用して描画する。

• periodic2_mesh_mode ({"centroid", "mesh"}, default "centroid") -- 周期セルへ wrap する単位。"centroid" は face ごと、"mesh" は mesh_id ごとに丸ごと移動して粒子形状を保つ。

• periodic2_repeat (int, default 0) -- 周期イメージの複製数。n を指定すると各周期軸方向に -n から +n までの (2n+1)^2 コピーを生成して描画する。0 は複製なし。

• axis_unit ({"m", "um", "nm"}, default "m") -- Coordinate unit used for 3D axes.

戻り値:

(figure, axes) from matplotlib.

戻り値の型:

tuple

例外:

ValueError -- If triangle geometry is unavailable.

beach.plot_charges(result)

Plot per-element charges as a bar chart (light: saved values only).

パラメータ:

result (RunResult or Beach-like object) -- Run result or object exposing result as RunResult.

戻り値:

(figure, axes) from matplotlib.

戻り値の型:

tuple

beach.plot_potential_mesh(result, *, cmap='viridis', view_elev=24.0, view_azim=-58.0, periodic2=None, apply_periodic2_mesh=False, periodic2_mesh_mode='centroid', periodic2_repeat=0, reference_point=None, axis_unit='m', config_path=None, library_path=None, source='auto', kernel=None)

Plot a 3D mesh colored by electric potential (heavy unless saved values are used).

パラメータ:

• result (RunResult or Beach-like object) -- Run result or object exposing result as RunResult.

• cmap (str, default "viridis") -- Matplotlib colormap name.

• view_elev (float, default 24.0) -- Elevation angle in degrees passed to Axes3D.view_init.

• view_azim (float, default -58.0) -- Azimuth angle in degrees passed to Axes3D.view_init.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting. See beach.compute_potential_mesh().

• apply_periodic2_mesh (bool, default False) -- True の場合、triangle 重心を周期セルへ wrap する平行移動を各 face に 適用して描画する。periodic2 が None なら近傍の beach.toml から 自動判定する。

• periodic2_mesh_mode ({"centroid", "mesh"}, default "centroid") -- 周期セルへ wrap する単位。"mesh" は粒子を割らずに表示したい場合に使う。

• periodic2_repeat (int, default 0) -- 周期イメージの複製数。n を指定すると各周期軸方向に -n から +n までの (2n+1)^2 コピーを生成して描画する。0 は複製なし。

• reference_point (iterable of float, {"species1_injection_center"}, or None, default None) -- 基準電位を差し引く参照点。None は絶対電位、"species1_injection_center" は species1 の注入面中心を基準にした電位差を描く。

• axis_unit ({"m", "um", "nm"}, default "m") -- Coordinate unit used for 3D axes.

• config_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• library_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• source ({"auto", "saved", "kernel"}, default "auto") -- Saved mesh_potential.csv or kernel evaluation; see beach.compute_potential_mesh().

• kernel (FieldKernel or None, default None) -- Open kernel built from this run that evaluates the potential with its own plan and charges and is not closed. periodic2 then only wraps and replicates the drawn mesh. None builds a kernel when one is needed.

戻り値:

(figure, axes) from matplotlib.

戻り値の型:

tuple

例外:

ValueError -- If potential reconstruction arguments are invalid.

beach.plot_potential_slices(result, *, box_min, box_max, grid_n=200, xy_z=None, yz_x=None, xz_y=None, chunk_size=2048, cmap='viridis', vmin=None, vmax=None, periodic2=None, reference_point=None, axis_unit='m', config_path=None, library_path=None, kernel=None)

Plot XY/YZ/XZ potential slices in one figure (heavy: native kernel).

パラメータ:

• result (RunResult or Beach-like object) -- Run result or object exposing result as RunResult.

• box_min (iterable of float) -- Lower simulation-box corner [x, y, z] in meters.

• box_max (iterable of float) -- Upper simulation-box corner [x, y, z] in meters.

• grid_n (int, default 200) -- Grid size per slice axis.

• xy_z (float or None, default None) -- Z coordinate of XY slice. None uses box center.

• yz_x (float or None, default None) -- X coordinate of YZ slice. None uses box center.

• xz_y (float or None, default None) -- Y coordinate of XZ slice. None uses box center.

• chunk_size (int, default 2048) -- Sampling chunk size for potential computation.

• cmap (str, default "viridis") -- Matplotlib colormap name.

• vmin (float or None, default None) -- Lower color limit. None selects automatically.

• vmax (float or None, default None) -- Upper color limit. None selects automatically.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting. See beach.compute_potential_points().

• reference_point (iterable of float, {"species1_injection_center"}, or None, default None) -- 基準電位を差し引く参照点。None は絶対電位、"species1_injection_center" は species1 の注入面中心を基準にした電位差を描く。

• axis_unit ({"m", "um", "nm"}, default "m") -- Coordinate unit used for slice axes.

• config_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• library_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• kernel (FieldKernel or None, default None) -- Open kernel built from this run, used as given and not closed; see beach.compute_potential_points(). None builds one for this call.

戻り値:

(figure, axes_array) from matplotlib.

戻り値の型:

tuple

例外:

ValueError -- If potential sampling or color-limit arguments are invalid.

class beach.Beach(output_dir='outputs/latest', *, config_path=None, library_path=None)

Session over one Fortran output directory.

A Beach owns the loaded result, its RunContext (the one place that resolves beach.toml), and the native field kernels built for it. Methods that need a kernel reuse kernel(), so one plan serves several figures. Close the session, or use it as a context manager, to release those kernels.

パラメータ:

• output_dir (str or pathlib.Path, default "outputs/latest") -- Directory containing Fortran output files.

• config_path (str, pathlib.Path, or None, default None) -- beach.toml used by config-aware analyses. None searches output_dir, its parent, and its grandparent.

• library_path (str, pathlib.Path, or None, default None) -- Native field-kernel shared library. None uses BEACH_FIELD_KERNEL_LIB or the default search.

analyze_coulomb_mobility(*, step=-1, config_path=None, library_path=None, gravity=(0.0, 0.0, -9.81), support_normal=None, support_kinds=('plane',), target_kinds=None, density_kg_m3=None, mu_static=None, mu_roll=None, adhesion_force_N=0.0)

Analyze per-object Coulomb mobility indicators (heavy: native kernel per object).

パラメータ:

• result (RunResult or Beach-like object) -- Run result or object exposing result as RunResult.

• step (int or None, default -1) -- History batch step used for charge snapshot. None uses final charges from charges.csv.

• config_path (str, pathlib.Path, or None, default None) -- Optional beach.toml path used for object labels and geometry metadata.

• gravity (iterable of float, default (0, 0, -9.81)) -- Gravity vector in meters per second squared.

• support_normal (iterable of float or None, default None) -- Support-normal direction. None uses -gravity when possible, otherwise +z.

• support_kinds (iterable of str or None, default ("plane",)) -- Object kinds treated as fixed supports and excluded from default targets.

• target_kinds (iterable of str or None, default None) -- Explicit target kinds to analyze. None means all non-support objects, falling back to all objects when no non-support object exists.

• density_kg_m3 (float or None, default None) -- Bulk density used to estimate weight for volumetric templates.

• mu_static (float or None, default None) -- Static-friction coefficient for slide-ratio estimation.

• mu_roll (float or None, default None) -- Rolling-resistance coefficient for roll-ratio estimation.

• adhesion_force_N (float, default 0.0) -- Additional normal adhesion resisting lift.

• library_path (str | Path | None)

戻り値:

Per-object force/torque summary and mobility indicators.

戻り値の型:

CoulombMobilityAnalysis

例外:

ValueError -- If arguments are invalid or no target objects are available.

メモ

Session method for beach.analysis.mobility.analyze_coulomb_mobility() with this run as result. library_path defaults to the session's.

animate_mesh(output_path=None, *, quantity='charge', fps=10, frame_stride=1, total_frames=None, cmap=None, periodic2=None, apply_periodic2_mesh=False, periodic2_repeat=0, reference_point=None, view_elev=None, view_azim=None, library_path=None, kernel=None)

Render mesh history as an animation (heavy for quantity="potential").

パラメータ:

• result (RunResult or Beach-like object) -- Run result or object exposing result as RunResult.

• output_path (str or pathlib.Path or None, default None) -- Output GIF path. If None, return a live FuncAnimation object.

• quantity ({"charge", "potential"}, default "charge") -- Quantity used for per-face coloring.

• fps (int, default 10) -- Frames per second.

• frame_stride (int, default 1) -- Use every frame_stride-th snapshot.

• total_frames (int or None, default None) -- Evenly sampled frame count. Cannot be combined with frame_stride != 1.

• cmap (str or None, default None) -- Matplotlib colormap name. None uses quantity-specific defaults.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting for potential mode. None の場合は 出力ディレクトリ近傍の beach.toml から自動判定する。

• apply_periodic2_mesh (bool, default False) -- True の場合、triangle 重心を周期セルへ wrap する平行移動を各 face に 適用して描画する。

• periodic2_repeat (int, default 0) -- 周期イメージの複製数。n を指定すると各周期軸方向に -n から +n までの (2n+1)^2 コピーを生成して描画する。0 は複製なし。

• reference_point (iterable of float, {"species1_injection_center"}, or None, default None) -- 基準電位を差し引く参照点。None は絶対電位、"species1_injection_center" は species1 の注入面中心を基準にした電位差を描く。

• view_elev (float or None, default None) -- 3D view elevation angle in degrees. None uses the default (24.0).

• view_azim (float or None, default None) -- 3D view azimuth angle in degrees. None uses the default (-58.0).

• library_path (str, pathlib.Path, or None, default None) -- Native kernel library for potential mode.

• kernel (FieldKernel or None, default None) -- Open kernel built from this run that evaluates potential mode with its own plan; its source charges are stepped through the history frames and then restored, and it is not closed. periodic2 then only wraps and replicates the drawn mesh. None builds a kernel for potential mode.

戻り値:

Written GIF path when output_path is provided, otherwise animation object.

戻り値の型:

pathlib.Path or matplotlib.animation.FuncAnimation

例外:

ValueError -- If arguments are invalid or history/geometry data is unavailable.

メモ

Session method for beach.plot.animation.animate_history_mesh() with this run as result. library_path defaults to the session's. A kernel-evaluating call receives the cached Beach.kernel() for its plan arguments as kernel; passing kernel, config_path, or another library_path builds a kernel for the call instead.

calc_coulomb(target, source, *, step=-1, torque_origin='target_center', periodic2=None, quadrature_order=7, config_path=None, library_path=None, kernel=None)

Compute force/torque on one panel group from another panel group (heavy: native kernel).

パラメータ:

• result (RunResult, RunContext, or Beach) -- Run to evaluate.

• target (int, MeshSelection, or iterable of those) -- Disjoint mesh groups; the force acts on target (group A).

• source (int, MeshSelection, or iterable of those) -- Disjoint mesh groups; the force acts on target (group A).

• step (int or None, default -1) -- History step whose charges are used. None uses charges.csv.

• torque_origin ({"target_center", "source_center", "origin"}, default "target_center") -- Torque reference point ("group_a_center" / "group_b_center" alias the first two).

• periodic2 (mapping or None, default None) -- Two-axis periodic setting. None resolves it from the run.

• quadrature_order (int, default 7) -- Gauss-Duffy order of the target-panel quadrature.

• config_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• library_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• kernel (FieldKernel or None, default None) -- Open kernel built from this run's full mesh, for example Beach.kernel(). During the call its source charges are those of source alone, and they are restored afterwards; it is not closed. Its plan is used as given, so periodic2 and library_path do not apply, and its uniform external field is excluded from the result. The full-mesh plan agrees with the default source-only plan to FMM accuracy. None builds a source-only kernel for this call and closes it.

戻り値:

Force and torque on both groups.

戻り値の型:

CoulombInteraction

メモ

Session method for beach.analysis.coulomb.calc_coulomb() with this run as result. library_path defaults to the session's. A kernel-evaluating call receives the cached Beach.kernel() for its plan arguments as kernel; passing kernel, config_path, or another library_path builds a kernel for the call instead.

calc_object_forces_kernel(*, step=-1, target_mesh_ids=None, periodic2=None, theta=None, leaf_max=None, order=None, config_path=None, library_path=None, kernel=None)

Compute object-wise net force with the native field kernel (heavy).

For each target object, its own source charges are zeroed before evaluating the target panel lattice is integrated with seventh-order Gauss-Duffy quadrature. A configured uniform sim.e0 is added to the target field, matching the simulator pusher semantics while avoiding central-cell primary self-force contamination.

kernel is an open kernel built from this run, for example Beach.kernel(). Its plan is used as given, so periodic2, theta, leaf_max, order, and library_path do not apply; its source charges are replaced by the step charges during the call and restored afterwards, and it is not closed. None builds a kernel for this call and closes it.

メモ

Session method for beach.analysis.field_kernel.calc_object_forces_kernel() with this run as result. library_path defaults to the session's. A kernel-evaluating call receives the cached Beach.kernel() for its plan arguments as kernel; passing kernel, config_path, or another library_path builds a kernel for the call instead.

パラメータ:

• step (int | None)

• target_mesh_ids (int | Iterable[int] | None)

• periodic2 (Mapping[str, object] | None)

• theta (float | None)

• leaf_max (int | None)

• order (int | None)

• config_path (str | Path | None)

• library_path (str | Path | None)

• kernel (FieldKernel | None)

戻り値の型:

tuple[KernelObjectForceRecord, ...]

close()

Close every cached native kernel. The loaded result stays available.

戻り値の型:

None

compute_electric_field(points, *, chunk_size=2048, periodic2=None, config_path=None, library_path=None, kernel=None)

Evaluate the triangle-P0 electric field at arbitrary points (heavy: native kernel).

パラメータ:

• result (RunResult, RunContext, or Beach) -- Run to evaluate.

• points (numpy.ndarray) -- Sampling points with shape (n_points, 3) in meters.

• chunk_size (int, default 2048) -- Number of points evaluated per kernel call.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting. None resolves it from the run.

• config_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• library_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• kernel (FieldKernel or None, default None) -- Open kernel built from this run, for example Beach.kernel(). It is evaluated with its own plan and charges and is not closed; periodic2 and library_path then do not apply. None builds a kernel for this call (latest history charges) and closes it.

戻り値:

Electric field in V/m with shape (n_points, 3).

戻り値の型:

numpy.ndarray

メモ

Session method for beach.analysis.field_lines.compute_electric_field_points() with this run as result. library_path defaults to the session's. A kernel-evaluating call receives the cached Beach.kernel() for its plan arguments as kernel; passing kernel, config_path, or another library_path builds a kernel for the call instead.

compute_potential(*, periodic2=None, reference_point=None, config_path=None, library_path=None, source='auto', kernel=None)

Evaluate triangle-P0 potential at every panel centroid (heavy unless saved values are used).

パラメータ:

• result (RunResult, RunContext, or Beach) -- Run to evaluate.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting. None resolves it from the run.

• reference_point (iterable of float, {"species1_injection_center"}, or None, default None) -- Point whose potential is subtracted. None returns absolute potential.

• config_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• library_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• source ({"auto", "saved", "kernel"}, default "auto") -- "saved" returns the simulator's mesh_potential.csv (light) and rejects periodic2, reference_point, and kernel. "kernel" always evaluates the native kernel (heavy). "auto" uses the saved values when they exist and none of periodic2, reference_point, or kernel is given, and the kernel otherwise.

• kernel (FieldKernel or None, default None) -- Open kernel built from this run, for example Beach.kernel(step=None). It is evaluated with its own plan and charges and is not closed; periodic2 and library_path then do not apply. None builds a kernel for this call and closes it.

戻り値:

Potential in volts with shape (mesh_nelem,).

戻り値の型:

numpy.ndarray

メモ

Session method for beach.analysis.potential.compute_potential_mesh() with this run as result. library_path defaults to the session's. A kernel-evaluating call receives the cached Beach.kernel() for its plan arguments as kernel; passing kernel, config_path, or another library_path builds a kernel for the call instead.

compute_potential_points(points, *, chunk_size=2048, periodic2=None, reference_point=None, config_path=None, library_path=None, kernel=None)

Evaluate triangle-P0 potential at arbitrary points (heavy: native kernel).

パラメータ:

• result (RunResult, RunContext, or Beach) -- Run to evaluate.

• points (numpy.ndarray) -- Sampling points with shape (n_points, 3) in meters.

• chunk_size (int, default 2048) -- Number of points evaluated per kernel call.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting. None resolves it from the run.

• reference_point (iterable of float, {"species1_injection_center"}, or None, default None) -- Point whose potential is subtracted. None returns absolute potential.

• config_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• library_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• kernel (FieldKernel or None, default None) -- Open kernel built from this run, for example Beach.kernel(step=None). It is evaluated with its own plan and charges and is not closed; periodic2 and library_path then do not apply. None builds a kernel for this call and closes it.

戻り値:

Potential in volts with shape (n_points,).

戻り値の型:

numpy.ndarray

メモ

Session method for beach.analysis.potential.compute_potential_points() with this run as result. library_path defaults to the session's. A kernel-evaluating call receives the cached Beach.kernel() for its plan arguments as kernel; passing kernel, config_path, or another library_path builds a kernel for the call instead.

compute_potential_slices(*, box_min, box_max, grid_n=200, xy_z=None, yz_x=None, xz_y=None, chunk_size=2048, periodic2=None, reference_point=None, config_path=None, library_path=None, kernel=None)

Sample triangle-P0 potential on XY, YZ, and XZ slices (heavy: native kernel).

The planes cross box_min-box_max at xy_z, yz_x, and xz_y (box center when None) on a grid_n x grid_n grid. The other arguments, including kernel, are those of compute_potential_points().

メモ

Session method for beach.analysis.potential.compute_potential_slices() with this run as result. library_path defaults to the session's. A kernel-evaluating call receives the cached Beach.kernel() for its plan arguments as kernel; passing kernel, config_path, or another library_path builds a kernel for the call instead.

パラメータ:

• box_min (Iterable[float])

• box_max (Iterable[float])

• grid_n (int)

• xy_z (float | None)

• yz_x (float | None)

• xz_y (float | None)

• chunk_size (int)

• periodic2 (Mapping[str, object] | None)

• reference_point (Iterable[float] | str | None)

• config_path (str | Path | None)

• library_path (str | Path | None)

• kernel (FieldKernel | None)

戻り値の型:

dict[str, PotentialSlice2D]

property context: RunContext

Return the run context (loads the result on first access).

戻り値:

Loaded result and its lazily resolved beach.toml.

戻り値の型:

RunContext

get_mesh(*mesh_ids, step=-1)

Return mesh selections for requested ids.

パラメータ:

• *mesh_ids (int) -- One or more mesh identifiers.

• step (int or None, default -1) -- History step used to select charges. -1 selects latest history, None uses final charges.

戻り値:

Single selection when one id is given, tuple otherwise.

戻り値の型:

MeshSelection or tuple[MeshSelection, ...]

例外:

ValueError -- If no mesh ids are provided or a mesh id is invalid.

get_mesh_charge(*mesh_ids, step=-1)

Return per-element charges for requested mesh ids.

パラメータ:

• *mesh_ids (int) -- One or more mesh identifiers.

• step (int or None, default -1) -- History step used to select charges.

戻り値:

Charge array for each requested mesh.

戻り値の型:

numpy.ndarray or tuple[numpy.ndarray, ...]

kernel(*, step=-1, periodic2=None, theta=None, leaf_max=None, order=None)

Return the session's native field kernel for one plan (heavy on first use).

The kernel is built with beach.analysis.field_kernel.field_kernel_from_result() and cached by its charge values, resolved field-kernel options, and the session's library_path. Equivalent defaults and explicit options, and steps with the same charges, share one kernel. The session owns the kernel: do not close it, and restore its charges after FieldKernel.update_charges(). close() and reload() release every cached kernel.

パラメータ:

• step (int or None, default -1) -- History step whose charges load the kernel. -1 selects the latest history snapshot, None the final charges.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting. None resolves it from the run.

• theta (float, int, int, or None, default None) -- FMM plan overrides. None uses the run's receipt or config.

• leaf_max (float, int, int, or None, default None) -- FMM plan overrides. None uses the run's receipt or config.

• order (float, int, int, or None, default None) -- FMM plan overrides. None uses the run's receipt or config.

戻り値:

Open kernel owned by this session.

戻り値の型:

FieldKernel

property mesh_ids: tuple[int, ...]

Return available mesh ids.

戻り値:

Sorted unique mesh identifiers.

戻り値の型:

tuple of int

object_interaction_snapshot(*, step=-1, config_path=None, periodic_model='configured', cache_dir=None, generation_tolerance=None, library_path=None)

Build one source snapshot from saved BEACH geometry and charges (heavy: native kernels).

メモ

Session method for beach.analysis.object_interaction.ObjectInteractionSnapshot.from_result() with this run as result. library_path defaults to the session's.

パラメータ:

• step (int | None)

• config_path (str | Path | None)

• periodic_model (str)

• cache_dir (str | Path | None)

• generation_tolerance (float | None)

• library_path (str | Path | None)

戻り値の型:

ObjectInteractionSnapshot

plot_bar()

Plot per-element charges as a bar chart (light: saved values only).

パラメータ:

result (RunResult or Beach-like object) -- Run result or object exposing result as RunResult.

戻り値:

(figure, axes) from matplotlib.

戻り値の型:

tuple

メモ

Session method for beach.plot.mesh.plot_charges() with this run as result.

plot_coulomb_force_matrix(*, step=-1, component='z', target_kinds=None, config_path=None, library_path=None, cmap='coolwarm', annotate=True, workers=1, kernel=None)

Plot an object-wise Coulomb-force matrix (heavy: native kernel).

パラメータ:

• result (RunResult or Beach-like object) -- Run result or object exposing result as RunResult.

• step (int or None, default -1) -- History batch step used for charge snapshot. None uses final charges from charges.csv.

• component ({"x", "y", "z"}, default "z") -- Force component rendered in the matrix.

• target_kinds (iterable of str or None, default None) -- Template kinds used as target objects. None means all objects.

• config_path (str, pathlib.Path, or None, default None) -- Optional beach.toml path used for object labels/order. None auto-detects near result.directory when possible.

• cmap (str, default "coolwarm") -- Matplotlib colormap name.

• annotate (bool, default True) -- Whether to draw scientific-notation values inside each cell.

• workers (int, default 1) -- Number of worker processes used for source/target force entries.

• kernel (FieldKernel or None, default None) -- Open full-mesh kernel built from this run, shared by every entry when workers == 1 (see beach.calc_coulomb()). Worker processes cannot share it, so with workers > 1 each entry builds its own kernel.

• library_path (str | Path | None)

戻り値:

(figure, axes) from matplotlib.

戻り値の型:

tuple

例外:

ValueError -- If no suitable objects are available or arguments are invalid.

メモ

Session method for beach.plot.matrix.plot_coulomb_force_matrix() with this run as result. library_path defaults to the session's. A kernel-evaluating call receives the cached Beach.kernel() for its plan arguments as kernel; passing kernel, config_path, or another library_path builds a kernel for the call instead.

plot_field_lines(seed_points, *, ds=None, max_steps=500, periodic2=None, direction='both', box_min=None, box_max=None, show_mesh=True, mesh_alpha=0.25, mesh_cmap='coolwarm', line_color=None, line_cmap='plasma', line_width=1.2, view_elev=24.0, view_azim=-58.0, title='Electric field lines', figsize=(9, 7), config_path=None, library_path=None, kernel=None)

Plot triangle-P0 field lines and an optional surface mesh (heavy: native kernel).

The tracing arguments, including kernel, are those of beach.trace_field_lines(). show_mesh overlays the mesh colored by surface charge density with mesh_cmap and mesh_alpha; lines use line_color or, when it is None, line_cmap. Returns (figure, axes).

メモ

Session method for beach.plot.field_lines.plot_field_lines_3d() with this run as result. library_path defaults to the session's. A kernel-evaluating call receives the cached Beach.kernel() for its plan arguments as kernel; passing kernel, config_path, or another library_path builds a kernel for the call instead.

パラメータ:

• seed_points (np.ndarray)

• ds (float | None)

• max_steps (int)

• periodic2 (Mapping[str, object] | None)

• direction (str)

• box_min (Iterable[float] | None)

• box_max (Iterable[float] | None)

• show_mesh (bool)

• mesh_alpha (float)

• mesh_cmap (str)

• line_color (str | None)

• line_cmap (str)

• line_width (float)

• view_elev (float)

• view_azim (float)

• title (str)

• figsize (tuple[float, float])

• config_path (str | Path | None)

• library_path (str | Path | None)

• kernel (FieldKernel | None)

戻り値の型:

tuple[Figure, Axes3D]

plot_mesh(*, cmap='coolwarm', view_elev=24.0, view_azim=-58.0, periodic2=None, apply_periodic2_mesh=False, periodic2_mesh_mode='centroid', periodic2_repeat=0, axis_unit='m')

Plot a 3D mesh colored by surface charge density (light: saved values only).

パラメータ:

• result (RunResult or Beach-like object) -- Run result or object exposing result as RunResult.

• cmap (str, default "coolwarm") -- Matplotlib colormap name.

• view_elev (float, default 24.0) -- Elevation angle in degrees passed to Axes3D.view_init.

• view_azim (float, default -58.0) -- Azimuth angle in degrees passed to Axes3D.view_init.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting used when apply_periodic2_mesh=True. None の場合は出力ディレクトリ近傍の beach.toml から自動判定する。

• apply_periodic2_mesh (bool, default False) -- True の場合、triangle 重心を周期セルへ wrap する平行移動を各 face に 適用して描画する。

• periodic2_mesh_mode ({"centroid", "mesh"}, default "centroid") -- 周期セルへ wrap する単位。"centroid" は face ごと、"mesh" は mesh_id ごとに丸ごと移動して粒子形状を保つ。

• periodic2_repeat (int, default 0) -- 周期イメージの複製数。n を指定すると各周期軸方向に -n から +n までの (2n+1)^2 コピーを生成して描画する。0 は複製なし。

• axis_unit ({"m", "um", "nm"}, default "m") -- Coordinate unit used for 3D axes.

戻り値:

(figure, axes) from matplotlib.

戻り値の型:

tuple

例外:

ValueError -- If triangle geometry is unavailable.

メモ

Session method for beach.plot.mesh.plot_charge_mesh() with this run as result.

plot_mesh_source_boxplot(*, quantity='charge', step=-1, showfliers=True, config_path=None, library_path=None)

Plot area-weighted boxplots per mesh source (heavy for potential not saved in mesh_potential.csv).

パラメータ:

• result (RunResult or Beach-like object) -- Run result or object exposing result as RunResult.

• quantity ({"charge", "potential"}, default "charge") -- Quantity used in boxplot values.

• step (int or None, default -1) -- History batch step used for charge snapshot. None uses final charges from charges.csv.

• showfliers (bool, default True) -- Whether outlier markers are rendered.

• config_path (str | Path | None)

• library_path (str | Path | None)

戻り値:

(figure, axes) from matplotlib.

戻り値の型:

tuple

例外:

ValueError -- If triangle geometry is unavailable or plot arguments are invalid.

メモ

Session method for beach.plot.boxplot.plot_mesh_source_boxplot() with this run as result. library_path defaults to the session's.

plot_potential(*, cmap='viridis', view_elev=24.0, view_azim=-58.0, periodic2=None, apply_periodic2_mesh=False, periodic2_mesh_mode='centroid', periodic2_repeat=0, reference_point=None, axis_unit='m', config_path=None, library_path=None, source='auto', kernel=None)

Plot a 3D mesh colored by electric potential (heavy unless saved values are used).

パラメータ:

• result (RunResult or Beach-like object) -- Run result or object exposing result as RunResult.

• cmap (str, default "viridis") -- Matplotlib colormap name.

• view_elev (float, default 24.0) -- Elevation angle in degrees passed to Axes3D.view_init.

• view_azim (float, default -58.0) -- Azimuth angle in degrees passed to Axes3D.view_init.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting. See beach.compute_potential_mesh().

• apply_periodic2_mesh (bool, default False) -- True の場合、triangle 重心を周期セルへ wrap する平行移動を各 face に 適用して描画する。periodic2 が None なら近傍の beach.toml から 自動判定する。

• periodic2_mesh_mode ({"centroid", "mesh"}, default "centroid") -- 周期セルへ wrap する単位。"mesh" は粒子を割らずに表示したい場合に使う。

• periodic2_repeat (int, default 0) -- 周期イメージの複製数。n を指定すると各周期軸方向に -n から +n までの (2n+1)^2 コピーを生成して描画する。0 は複製なし。

• reference_point (iterable of float, {"species1_injection_center"}, or None, default None) -- 基準電位を差し引く参照点。None は絶対電位、"species1_injection_center" は species1 の注入面中心を基準にした電位差を描く。

• axis_unit ({"m", "um", "nm"}, default "m") -- Coordinate unit used for 3D axes.

• config_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• library_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• source ({"auto", "saved", "kernel"}, default "auto") -- Saved mesh_potential.csv or kernel evaluation; see beach.compute_potential_mesh().

• kernel (FieldKernel or None, default None) -- Open kernel built from this run that evaluates the potential with its own plan and charges and is not closed. periodic2 then only wraps and replicates the drawn mesh. None builds a kernel when one is needed.

戻り値:

(figure, axes) from matplotlib.

戻り値の型:

tuple

例外:

ValueError -- If potential reconstruction arguments are invalid.

メモ

Session method for beach.plot.mesh.plot_potential_mesh() with this run as result. library_path defaults to the session's. A kernel-evaluating call receives the cached Beach.kernel() for its plan arguments as kernel; passing kernel, config_path, or another library_path builds a kernel for the call instead.

plot_potential_slices(*, box_min, box_max, grid_n=200, xy_z=None, yz_x=None, xz_y=None, chunk_size=2048, cmap='viridis', vmin=None, vmax=None, periodic2=None, reference_point=None, axis_unit='m', config_path=None, library_path=None, kernel=None)

Plot XY/YZ/XZ potential slices in one figure (heavy: native kernel).

パラメータ:

• result (RunResult or Beach-like object) -- Run result or object exposing result as RunResult.

• box_min (iterable of float) -- Lower simulation-box corner [x, y, z] in meters.

• box_max (iterable of float) -- Upper simulation-box corner [x, y, z] in meters.

• grid_n (int, default 200) -- Grid size per slice axis.

• xy_z (float or None, default None) -- Z coordinate of XY slice. None uses box center.

• yz_x (float or None, default None) -- X coordinate of YZ slice. None uses box center.

• xz_y (float or None, default None) -- Y coordinate of XZ slice. None uses box center.

• chunk_size (int, default 2048) -- Sampling chunk size for potential computation.

• cmap (str, default "viridis") -- Matplotlib colormap name.

• vmin (float or None, default None) -- Lower color limit. None selects automatically.

• vmax (float or None, default None) -- Upper color limit. None selects automatically.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting. See beach.compute_potential_points().

• reference_point (iterable of float, {"species1_injection_center"}, or None, default None) -- 基準電位を差し引く参照点。None は絶対電位、"species1_injection_center" は species1 の注入面中心を基準にした電位差を描く。

• axis_unit ({"m", "um", "nm"}, default "m") -- Coordinate unit used for slice axes.

• config_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• library_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• kernel (FieldKernel or None, default None) -- Open kernel built from this run, used as given and not closed; see beach.compute_potential_points(). None builds one for this call.

戻り値:

(figure, axes_array) from matplotlib.

戻り値の型:

tuple

例外:

ValueError -- If potential sampling or color-limit arguments are invalid.

メモ

Session method for beach.plot.slices.plot_potential_slices() with this run as result. library_path defaults to the session's. A kernel-evaluating call receives the cached Beach.kernel() for its plan arguments as kernel; passing kernel, config_path, or another library_path builds a kernel for the call instead.

reload()

Close the cached kernels and reload output files from disk.

戻り値:

Refreshed parsed result.

戻り値の型:

RunResult

property result: RunResult

Return the loaded run result.

戻り値:

Parsed result for output_dir.

戻り値の型:

RunResult

scene(*, step=-1, config_path=None, transform_backend='numpy', library_path=None)

Create a scene from a BEACH output snapshot (saved values only, light).

config_path and library_path become the defaults of the scene's kernel methods; a Beach result contributes its own config path.

メモ

Session method for beach.analysis.scene.BeachScene.from_result() with this run as result. library_path defaults to the session's.

パラメータ:

• step (int | None)

• config_path (str | Path | None)

• transform_backend (Literal['numpy', 'numba', 'auto'])

• library_path (str | Path | None)

戻り値の型:

BeachScene

trace_field_lines(seed_points, *, ds=None, max_steps=500, periodic2=None, direction='both', box_min=None, box_max=None, config_path=None, library_path=None, kernel=None)

Trace field lines with RK4 on the triangle-P0 field (heavy: native kernel).

パラメータ:

• result (RunResult, RunContext, or Beach) -- Run to evaluate.

• seed_points (numpy.ndarray) -- Starting points with shape (n_seeds, 3) in meters.

• ds (float or None, default None) -- Step length in meters. None uses half the mean mesh edge length.

• max_steps (int, default 500) -- Maximum steps per direction.

• periodic2 (mapping or None, default None) -- Two-axis periodic setting. None resolves it from the run.

• direction ({"both", "forward", "backward"}, default "both") -- Trace along the field, against it, or both.

• box_min (iterable of float or None, default None) -- Box that stops a line when it is left.

• box_max (iterable of float or None, default None) -- Box that stops a line when it is left.

• config_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• library_path (str, pathlib.Path, or None, default None) -- Explicit beach.toml and native kernel library.

• kernel (FieldKernel or None, default None) -- Open kernel built from this run, for example Beach.kernel(). It is evaluated with its own plan and charges and is not closed; periodic2 and library_path then do not apply. None builds a kernel for this call (latest history charges) and closes it.

戻り値:

One (n_points_i, 3) polyline per seed.

戻り値の型:

list of numpy.ndarray

メモ

Session method for beach.analysis.field_lines.trace_field_lines() with this run as result. library_path defaults to the session's. A kernel-evaluating call receives the cached Beach.kernel() for its plan arguments as kernel; passing kernel, config_path, or another library_path builds a kernel for the call instead.

公開定数と summary 定義表

クーロン定数と、summary の読み込みに使う定義表です。

beach.K_COULOMB = 8987551792.3

Convert a string or number to a floating-point number, if possible.

beach.SUMMARY_FIELDS

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.