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.
Domain |
Compute or data API |
Plot or output API |
|---|---|---|
Divertor |
|
|
Transport |
|
|
Sources |
|
|
Mesh slices |
|
|
Distribution moments |
|
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.
Selector |
Return |
Data included |
|---|---|---|
|
|
Selected coefficient families and source groups on normalized flux |
|
|
XGC and optional TRANSP radial curves, with reference path |
|
|
Local and cumulative radial rates plus the total time trace |
|
|
XGC and optional TRANSP fueling or particle/energy balance curves |
|
|
Particle and energy panels, including fitted curves or target traces |
|
|
Heat-load widths, references and bands, or a target load map |
|
|
Time/space maps or selected surface and sight-line curves |
|
|
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.