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.

.. list-table:: Analysis entry points
   :header-rows: 1
   :widths: 18 39 43

   * - 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.