pyna.topo.topology_eval

Fast single-config magnetic topology evaluator — device-agnostic.

Supports arbitrary magnetic-confinement field caches via DeviceConfig.

All heavy numerics go through the cyna C++ extension:

– trace_poincare_batch_twall – single-section Poincare (with twall) – trace_poincare_multi – simultaneous multi-section Poincare – trace_connection_length_twall – binary search for LCFS seed – trace_orbit_along_phi – dense phi-parameterised orbit (for iota) – compute_A_matrix_batch – Jacobian A(r,z,phi) for DPm integration

Python / scipy are used only as fallbacks when cyna is unavailable.

Attributes

DEFAULT_DEVICE_CONFIG
EAST_CONFIG
W7X_CONFIG

Classes

DeviceConfig	Device-agnostic parameter configuration for topology evaluation.
TopologyEval	Result of evaluate_topology().

Functions

evaluate_topology(→ TopologyEval)

Evaluate magnetic topology for one field configuration.

Module Contents

class pyna.topo.topology_eval.DeviceConfig

Device-agnostic parameter configuration for topology evaluation.

Parameters:

• R_ax_guess (float) – Initial guess for magnetic axis R [m] (used for Newton refinement).

• Z_ax_guess (float) – Initial guess for magnetic axis Z [m].

• a_minor (float) – Minor radius [m] (used for r-normalisation).

• phi_sections (list) – Poincaré section list, e.g. [0, π/4, π/2, 3π/4].

• wall_file (str or None) – Path to wall geometry file. None → use field-grid boundary.

• fp_pkl_path (str or None) – Path to pre-computed fixed-point pkl. None → live search.

• n_sym (int) – Toroidal symmetry number (for example W7X=5, EAST=1).

• island_period (int) – Period of outermost island chain (used for X-point DPm integration).

• R_search_min (float) – Lower bound of fixed-point search domain [m].

• R_search_max (float) – Upper bound of fixed-point search domain [m].

• name (str) – Human-readable device name (auto-set in presets).

R_ax_guess: float

Z_ax_guess: float

a_minor: float

phi_sections: list

wall_file: str | None

fp_pkl_path: str | None

n_sym: int = 1

island_period: int = 3

R_search_min: float = 0.5

R_search_max: float = 2.0

name: str = 'unknown'

pyna.topo.topology_eval.DEFAULT_DEVICE_CONFIG

pyna.topo.topology_eval.EAST_CONFIG

pyna.topo.topology_eval.W7X_CONFIG

class pyna.topo.topology_eval.TopologyEval

Result of evaluate_topology().

Fields that were not requested (compute_* = False) will be None.

R_ax: float

Z_ax: float

lcfs_R: numpy.ndarray | None

lcfs_Z: numpy.ndarray | None

V_lcfs: float

config_type: str

iota_profile: tuple | None

xpt_DPm_list: list | None

elapsed_s: float = 0.0

device_name: str = 'unknown'

pyna.topo.topology_eval.evaluate_topology(field_cache: dict, device: DeviceConfig = DEFAULT_DEVICE_CONFIG, compute_iota: bool = True, compute_xpt_DPm: bool = True, compute_lcfs_contour: bool = True, compute_manifolds: bool = False, n_core: int = 20, n_core_turns: int = 150, n_lcfs_turns: int = 200, n_iota: int = 15, n_iota_turns: int = 100, fp_pkl_path: str | None = None, island_period: int | None = None, DPhi: float = 0.05) → TopologyEval

Evaluate magnetic topology for one field configuration.

Parameters:

• field_cache (dict) – Field cache dict with keys BR, BZ, BPhi, R_grid, Z_grid, Phi_grid.

• device (DeviceConfig) – Device configuration. Defaults to a generic public configuration.

• compute_iota (bool) – Whether to compute the ι profile. Default True.

• compute_xpt_DPm (bool) – Whether to compute X-point monodromy matrix DPm (incl. λ_u). Default True.

• compute_lcfs_contour (bool) – Whether to return LCFS scatter points (lcfs_R, lcfs_Z). Default True. V_lcfs is always computed regardless of this flag.

• compute_manifolds (bool) – Whether to compute manifolds (slow). Default False.

• n_core (int) – Number of core Poincare seeds (radial sweep).

• n_core_turns (int) – Poincare turns for core seeds. Also used for iota profile.

• n_lcfs_turns (int) – Poincare turns for LCFS seed tracing.

• n_iota (int) – Number of radial iota points (subset of n_core grid).

• n_iota_turns (int) – Ignored (iota derived from already-traced core Poincare crossings).

• fp_pkl_path (str or None) – Legacy override: path to a fixed-point pickle file. If set, overrides device.fp_pkl_path.

• island_period (int or None) – Override device.island_period if set.

• DPhi (float) – RK4 toroidal step [rad].

Returns:

TopologyEval – Fields not requested will be None: - iota_profile = None if compute_iota=False - xpt_DPm_list = None if compute_xpt_DPm=False - lcfs_R/lcfs_Z = None if compute_lcfs_contour=False

Examples

# Optuna fast mode (equivalent to old fast_mode=True) evaluate_topology(fc, compute_iota=False, compute_xpt_DPm=False, compute_lcfs_contour=False)

# Full analysis (all defaults True) evaluate_topology(fc)

# Iota + V only, no DPm evaluate_topology(fc, compute_xpt_DPm=False)