Reusable analysis workflows

The xgc_analysis.analysis package contains scientific computations and figure builders that can be called from a Python script or notebook. Functions take a Simulation, catalog, data record, or path as documented by each module. They do not accept GUI render contexts. XGC-Devel Monitor plugins translate selected frames and options into these calls.

Analysis entry points
Domain	Compute or data API	Plot or output API
Divertor	`analysis.divertor`: mapped heatdiag profiles, Eich widths, target totals, and load maps	`analysis.divertor.plots`: caller-owned Matplotlib figures
Transport	`analysis.transport.neoclassical`, `combined_coefficients`, `coefficient_comparison`, and `potential_gradient`	`neoclassical_plots` returns a figure; `neoclassical_workflow` explicitly writes SVG or BP output
Sources	`analysis.sources.diagnostics` and `balance`	Results can be plotted by an application without a GUI dependency
Mesh slices	`analysis.slicing.mesh_slicing` and `mesh_time_slicing`	`analysis.slicing.plotting` returns R-Z and time-map figures
Distribution moments	`analysis.moments.distribution`	Result records retain the selected species and physical components

Shared midplane geometry is in analysis.geometry. It maps flux-surface crossings to inner and outer midplane radii and is used by divertor and transport computations. SOL volume-to-wall mapping lives with mesh geometry in mesh.sol_wall_mapping; wall-loss rate analysis is in analysis.divertor.wall_loss_rates.

Selection and provenance

Compute functions document their units and selection rules. Divertor selected_frame_index identifies the interval ending at the selected heatdiag frame; an explicit time window takes precedence. Neoclassical and time-slice functions accept logical step or physics-time windows and return records with selected steps or time coordinates. Plot functions take these records and return figures owned by the caller. Saving a figure or BP result requires an explicit call to a save or workflow function.

Long divertor computations accept AnalysisHooks with optional cancellation, phase, and log callbacks. Other long computations accept an optional check_cancel callback. Scripts may omit these hooks. The Monitor adapters pass GUI request hooks when present.

Example:

from xgc_analysis.analysis.divertor import (
    compute_divertor_eich_profiles,
    plot_divertor_eich_profiles,
)

profiles = compute_divertor_eich_profiles(run_dir, simulation=simulation)
figure = plot_divertor_eich_profiles(profiles)
figure.savefig("divertor.svg")

Matplotlib backend selection belongs to the calling application or test environment. mesh.plotting.plot_grid_contour neither selects a backend nor writes img.svg implicitly; pass filename to save explicitly.