XGC-GUI

XGC-GUI allows manipulation and visualization of XGC inputs/outputs located locally or on a remote machine, all inside a user’s browser.

XGC-GUI is under development. Please report any issues or feature requests to Aaron.

Features

Editor

In the Editor, users can:

  • Create, load, and save XGC input files on the target machine

  • View and edit input parameters using up-to-date descriptions and parent/child relationships

  • Check for invalid or deprecated input parameters

  • Generate a mesh preview from the input file mesh settings

  • Run XGC’s dryrun, quickstart and launch a batch script (beta)

Monitor

In the Monitor, users can

  • Browse .bp sources in a selected directory

  • Switch between the directory-scan data source and the XGC catalog backend when the required Python runtime is available

  • Inspect available variables for each source and route them into Panes for visualization

  • Render common graphics like vertex mesh plots that match xgc.mesh.bp dimensions, as well as basic line plots and color plots

  • Use plugin renderers from utils/input_gui/plugins/monitor/ for custom visualizations

  • Add their own custom visualization plugins

  • Save and load custom dashboard configurations

  • Auto-refresh visualizations to watch a simulation run in real-time

The data-source panel has two modes:

  • Directory Scan directly discovers .bp products under a directory and reads them without XGC-analysis-specific runtime support.

  • XGC Catalog uses the XGC-Analysis catalog/provider path to browse catalog products from either a directory or an HPC campaign .aca file.

When the XGC catalog runtime is unavailable in the active Python environment, the GUI disables the catalog mode and keeps Directory Scan available.

Catalog Mode

When catalog mode is active, the Monitor can

  • Browse data products from either a directory-backed catalog or a campaign archive

  • Show catalog runtime status, reader activity, and persistent Simulation status

  • Create and reuse a persistent XGC-Analysis Simulation object when the required catalog products and text artifacts are present

  • Run XGC-specific Monitor plugins that use the provider-managed catalog/session context

The Monitor keeps catalog and Simulation lifecycle controls in the Data Sources panel. A green/yellow/red status light indicates whether a resource is ready, processing, or unavailable.

Setup

First, set up a Python environment on your target machine (where your inputs/diagnostics are):

python3 -m venv ~/venvs/xgc-gui
source ~/venvs/xgc-gui/bin/activate
python3 -m pip install flask numpy matplotlib adios2

Next, if your target machine is not local, create an SSH tunnel from your local machine:

ssh -L 5080:127.0.0.1:5080 <user>@<remote-host>

You may need a different host or port. Then, on the target machine:

# Activate the Python environment
source ~/venvs/xgc-gui/bin/activate
# Enable xgc commands
source ~/path/to/XGC-Devel/utils/xgc_shell/init
# Launch the Python server:
xgc_gui
# Or if you need a different host or port:
XGC_INPUT_GUI_HOST=127.0.0.1 XGC_INPUT_GUI_PORT=5080 xgc_gui
# Launch with an input file preloaded
xgc_gui path/to/my_input
# Launch with a work directory preloaded
xgc_gui path/to/my_work_dir
# Launch with a source file preloaded
xgc_gui path/to/xgc.my_output.bp
# Launch the Monitor with a saved dashboard configuration
xgc_gui path/to/xgc.my_output.bp path/to/dashboard.xgcg
# A configuration alone uses the current directory as the Monitor root
xgc_gui path/to/dashboard.xgcg

If running locally, xgc_gui will automatically open the GUI in your default browser. (Disable that with XGC_OPEN_BROWSER=0). If remote, manually open the GUI locally in your browser of choice at:

http://127.0.0.1:5080

Developer Notes

Developer-facing architecture notes for Monitor plugins, provider backends, catalog mode, and request handling live in Docs/xgc_gui_developer.rst.