XGC-GUI Developer Notes

Overview

The browser GUI under utils/input_gui/ has two major parts:

  • The Editor for manipulating XGC input files

  • The Monitor for browsing and visualizing output data

The Monitor is intentionally split into separate concerns:

  • GUI orchestration and pane state live in the Flask app and browser code

  • Data-provider backends manage provider-specific runtime state and expensive sessions

  • Plugins adapt Monitor context into plotting or analysis workflows

  • Scientific analysis logic lives downstream in reusable libraries such as XGC-Analysis

Data Provider Backends

The Monitor should depend on explicit backend adapters rather than on provider-private state. The current XGC backend exposes two user-facing data source modes:

  • directory-scan for direct ADIOS/BP browsing

  • catalog for the XGC-Analysis-backed catalog/provider path

The XGC provider owns provider-specific runtime objects such as

  • cached catalogs

  • persistent Simulation objects

  • worker processes used to isolate catalog-backed plot requests

  • request tracking and cancellation state

The generic Monitor should consume stable backend payloads and hooks rather than reaching through those provider internals directly.

Monitor Request Workflow

For a typical plot request:

  1. The browser selects a source, variable, renderer, frame, and pane options.

  2. The Flask app routes the request either to directory-scan code paths or to the provider backend.

  3. Built-in renderers either read data directly or ask the provider/catalog for the selected variable array.

  4. Plugin renderers receive a small context dictionary containing source metadata, selected data, pane options, and request hooks.

  5. The Monitor serializes the resulting Matplotlib figure or image to PNG for display in the pane.

In catalog mode, request and lock state are tracked explicitly so the UI can show active requests, waiting readers, and stale or timed-out work.

Plugins

Monitor plugins live under utils/input_gui/plugins/monitor/. The GUI expects a small contract:

  • supports(meta) advertises whether the renderer applies to a selected variable

  • options_schema(meta) describes plugin-specific pane controls

  • render(ctx) returns a figure/image payload

Plugins should stay thin. If a workflow is scientifically meaningful outside the GUI, the heavy lifting should live in a reusable downstream module and the plugin should mainly

  • interpret GUI options

  • map Monitor frame selection into analysis inputs

  • forward optional request/progress/cancellation hooks

  • format the resulting plot

Catalog And Simulation Workflow

In XGC catalog mode, the provider is responsible for

  • reporting whether XGC-Analysis and its required modules are importable

  • creating or closing cached catalogs

  • checking whether the products/texts required for Simulation are present

  • creating or closing a persistent Simulation object

  • passing provider-owned context to plugins

The GUI should not re-implement XGC-Analysis availability checks or Simulation prerequisite logic on its own.

Design Rules

When extending the Monitor:

  • Keep the Editor backend independent of Monitor/provider changes.

  • Preserve the ability to use XGC-Analysis from ordinary scripts and notebooks.

  • Prefer optional hooks over GUI-specific control flow in scientific code.

  • Keep provider-specific state ownership explicit.

  • Treat worker processes and source readers as infrastructure, not as places to embed scientific workflow logic.