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: typed plot data for each figure and caller-owned Matplotlib figures

Transport

analysis.transport.neoclassical, combined_coefficients, coefficient_comparison, and potential_gradient

neoclassical_plots and plot_views select self-describing plot data and return figures; neoclassical_workflow explicitly writes full-result SVG or BP output

Sources

analysis.sources.diagnostics and balance

analysis.sources.plots selects typed rate and balance views and returns figures without a GUI dependency

Mesh slices

analysis.slicing.mesh_slicing and mesh_time_slicing

analysis.slicing.plotting selects typed R-Z, mesh-slice, and time-map views and returns 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.

Neoclassical plot data and BP sidecars

neoclassical_plot_data selects the curves, derived curves, coordinate, and displayed temporal-spread arrays for one view. PlotData.to_dict() returns named NumPy arrays with long and short names, physics symbols, units, dimensions, and roles. PlotData.write_bp(path) writes those same arrays to one BP step with corresponding variable attributes. A plot-data BP file is a figure sidecar; write_neoclassical_bp continues to write the complete neoclassical analysis result.

For standalone analysis, neoclassical_transport_data(result) returns a PlotDataCollection containing all available neoclassical plot groups. Use its plots and variables attributes in Python scripts: each plot has selection metadata and named curves, while variables provides one shared entry per coordinate, curve, or uncertainty array. The collection is the primary Python API for building new figures. to_dict() is an interchange view with plots (each figure’s metadata and variable names) and variables (named NumPy arrays and physical metadata). write_bp(path) writes that variable collection to one BP package; plots_metadata_json records plot membership and selection. The per-figure API remains available for image sidecars.

The symbol field contains LaTeX math-mode content without $ delimiters (for example, \psi_{N} or q_{i}). Wrap it in $...$ when using it as a Matplotlib math-text label. short_name is the machine-readable BP variable name.

Example:

from xgc_analysis.analysis.transport.neoclassical import compute_neoclassical_transport
from xgc_analysis.analysis.transport.neoclassical_plots import (
    neoclassical_plot_data, neoclassical_transport_data,
    plot_neoclassical_plot_data,
)

result = compute_neoclassical_transport(simulation)
all_plots = neoclassical_transport_data(result)
all_arrays_and_labels = all_plots.to_dict()  # optional dictionary view
all_plots.write_bp("neoclassical_plots.bp")
view = neoclassical_plot_data(result, "total_current", uncertainty_sigma=2)
arrays_and_labels = view.to_dict()
view.write_bp("total_current.bp")
figure = plot_neoclassical_plot_data(view)
figure.savefig("total_current.svg")

To build a new figure that compares curves from different standard views, select them by name and check their coordinate and units. In this example, jpar_plasma is XGC’s total parallel plasma current; the XGC bootstrap estimate is that current after subtracting the modeled Ohmic contribution. Both use the same psi_pol_norm coordinate and A m^-2 units:

from matplotlib import pyplot as plt

total = all_plots.plots["total_current"].variables["jpar_plasma"]
bootstrap = all_plots.plots["bootstrap_current"].variables["xgc_bootstrap_estimate"]
psi = all_plots.variables["psi_pol_norm"]
assert total.dimensions == bootstrap.dimensions == ("psi_pol_norm",)
assert total.units == bootstrap.units

fig, ax = plt.subplots()
ax.plot(psi.values, total.values, label=rf"${total.symbol}$")
ax.plot(psi.values, bootstrap.values, label=rf"${bootstrap.symbol}$")
ax.set(xlabel=rf"${psi.symbol}$", ylabel=total.units)
ax.legend()
fig.savefig("current_comparison.svg")

The view records selected gsteps, physics-time bounds, sample count, source product, averaging settings, and plot options. source_uri can be supplied when the run directory or ACA location is known. The Monitor export adds GUI source and plugin settings in a JSON sidecar.

Other Monitor-backed analysis views

The remaining Monitor-backed analysis functions also expose typed plot data. Call the compute function first, then a selector below. A PlotData represents one figure; a PlotDataCollection holds multiple standard views or panels. Use their variables and metadata directly to make a new figure. to_dict() provides an interchange mapping, and write_bp(path) persists the same named arrays with variable attributes. Supply source_uri to record the run-directory or ACA location when known.

Plot-data selectors

Selector

Return

Data included

combined_transport_plot_data

PlotData

Selected coefficient families and source groups on normalized flux

coefficient_comparison_plot_data and potential_gradient_plot_data

PlotData

XGC and optional TRANSP radial curves, with reference path

source_rate_plot_data

PlotDataCollection

Local and cumulative radial rates plus the total time trace

particle_fueling_plot_data and balance_plot_data

PlotData

XGC and optional TRANSP fueling or particle/energy balance curves

divertor_eich_plot_data and divertor_target_totals_plot_data

PlotDataCollection

Particle and energy panels, including fitted curves or target traces

divertor_lambda_q_plot_data and divertor_load_map_plot_data

PlotData

Heat-load widths, references and bands, or a target load map

mesh_time_map_plot_data and mesh_slice_plot_data

PlotData

Time/space maps or selected surface and sight-line curves

rz_diagnostic_plot_data

PlotDataCollection

Radial profile and/or interpolated R-Z raster with selected overlays

For example, to compare source rates from the same computation in a script:

from xgc_analysis.analysis.sources.diagnostics import compute_source_rates
from xgc_analysis.analysis.sources.plots import source_rate_plot_data
from matplotlib import pyplot as plt

rates = compute_source_rates(simulation, channel="fueling", source="neutral", species="i")
views = source_rate_plot_data(rates, source_uri="/path/to/run")
psi = views.variables["psi_pol_norm"].values
local = views.plots["local"].variables["fueling_neutral_i_local"]
cumulative = views.plots["cumulative"].variables["fueling_neutral_i_cumulative"]
assert local.units == cumulative.units
fig, ax = plt.subplots()
ax.plot(psi, local.values, label=local.long_name)
ax.plot(psi, cumulative.values, label=cumulative.long_name)
ax.legend()
views.write_bp("source_rates.bp")

The R-Z selector exports the interpolated raster used by the image, not only the original nodal field. Mesh-slice views likewise include the selected surface, time, or sight-line coordinates. Display limits are plot settings; they do not truncate the exported data arrays.

analysis.moments.distribution and analysis.divertor.wall_loss_rates currently provide compute results without a corresponding Monitor plot. They remain typed scientific results and are outside this plot-data contract until a plotting view is added for them.