GUI Overview

Purpose

OLMT_GUI.py provides a wxPython-based graphical user interface for running single-site ELM/ALM simulations. It is a wrapper around site_fullrun.py and related scripts, offering point-and-click configuration as an alternative to command-line invocation. The GUI supports both single-site runs and ensemble-based uncertainty quantification workflows.

Launch Instructions

Run from the OLMT repository root:

python OLMT_GUI.py

Dependencies:

  • wxPython (required for the GUI framework)

  • Standard OLMT runtime dependencies (see main README)

GUI Components

The interface is organized into three vertical panels:

Left Panel: Basic Configuration

  • Input data directory: Path to the E3SM/CESM input data tree (defaults vary by hostname; see ccsm_input at line 875).

  • Model run directory: Path where CIME case directories will be created.

  • Site group: Choose from available site groups (AmeriFlux, NGEEArctic, etc.). Changing this reloads the site list from <ccsm_input>/lnd/clm2/PTCLM/<sitegroup>_sitedata.txt.

  • Site: Multi-select list of sites to run. Selecting “all” runs every site in the group.

  • Case prefix: String prepended to case directory names.

  • Run type: Choose one of:

    • ad spinup — accelerated decomposition spinup (default 250 years)

    • final spinup — biomass/nutrient equilibration (default 250 years)

    • transient — historical simulation (default 150 years)

    • full simulation — runs the entire three-phase sequence with diagnostics

  • # of years: Simulation length (auto-populated when Run type changes).

Middle Panel: Site-Specific Options and Model Configuration

Site information (top): Read-only display of selected site’s lat/lon and dominant PFTs.

Site-specific options:

  • Make surface data files: Generate domain/surface/landuse files via makepointdata.py (checked by default).

  • Use site-level data in surface data files: Apply site-specific PFT/soil data from _pftdata.txt / _soildata.txt (checked by default).

  • Use site parameters: Passed as --siteparms (checked by default).

Model configuration:

  • Use satellite phenology: Switches to ICLM45 / ICLM45CB compsets (unchecked by default: prognostic BGC).

  • Use ECA (RD if not selected): Toggles between ECA and RD nutrient competition schemes.

  • Use Century (CTC if not selected): Toggles between Century (CNT) and CTC decomposition.

  • Carbon only mode: BGC-C (unchecked: CNP default).

  • Carbon-nitrogen mode: BGC-CN (unchecked: CNP default).

  • Use wildfire submodel: Enable fire model (checked by default).

  • Use dynamic rooting: Enable dynamic root distribution (unchecked by default).

  • No datm (coupler bypass): Enable cpl_bypass mode (checked by default).

  • Use hourly timestep: Run at 1-hour resolution (checked by default).

  • Use cru-ncep forcing data: Select CRUNCEP met forcing (mutually exclusive with other forcing flags).

  • Use gswp3 forcing data: Select GSWP3 met forcing.

  • Use c14: Enable C14 tracer (unchecked by default).

File for parameter mods: Path to a custom parameter file (passed as --parm_file). Use the “Browse” button to select.

Configure, build and run: Click “Begin simulation” to generate and execute the appropriate command.

Right Panel: Uncertainty Quantification and Plotting

Uncertainty Quantification:

  • Ensemble File: Path to a parm_list file defining parameter ranges (see examples/parm_list*). Selecting a file auto-populates the ensemble member count.

  • Run Monte Carlo ensemble: Generate random parameter samples (alternative to providing an ensemble file).

  • Number of ensemble members: Total ensemble size (auto-set when loading an ensemble file).

  • Number of processors to use: MPI ranks for ensemble execution (defaults to 256; capped at n_ensemble + 1).

Plotting and Diagnostics:

  • Variables to plot: Multi-select list (GPP, NEE, NPP, TLAI, TOTSOMC, TOTVEGC).

  • Generate plots: Invokes plotcase.py with the selected variables, sites, and compset. Requires completed simulations.

  • View/Edit Files: Opens the parameter file in Emacs (line 695: hard-coded to emacs <file> &).

Workflow

Single-site example:

  1. Select site group (e.g., “AmeriFlux”).

  2. Choose one or more sites from the list.

  3. Set case prefix (e.g., “test_run”).

  4. Choose “full simulation” to run the three-phase BGC sequence.

  5. Adjust model configuration checkboxes as needed.

  6. Click “Begin simulation”.

The GUI builds a site_fullrun.py command with the appropriate flags and invokes it via os.system() (line 855). Output is printed to the terminal where the GUI was launched.

For ensemble runs:

  1. Complete steps 1–5 above (Run type should be ad spinup, final spinup, or transient, not full simulation).

  2. In the right panel, browse for an ensemble file or check “Run Monte Carlo ensemble”.

  3. Set the number of processors.

  4. Click “Begin simulation”.

The GUI will append --ensemble_file or --mc_ensemble to the command.

Plotting results:

  1. After simulations complete, select sites and variables in the right panel.

  2. Click “Generate plots”.

This invokes plotcase.py --case <prefix> --site <sites> --compset <compset> --spinup --vars <vars> --csmdir <rundir>.

Limitations vs Command-Line

Not exposed in the GUI:

  • --model_root: The GUI hard-codes this to /home/<user>/models/ACME for full simulations (line 810). Single-phase runs omit it (assumes OLMT scripts will handle it internally or expect it as an environment variable).

  • --srcmods_loc: Not configurable; no custom source modifications.

  • --metdir: Forcing data paths are implicit (derived from --ccsm_input).

  • --eco2_file, --ssp_rcp: No CO2 scenario control.

  • Advanced spinup options (--run_startyear, --align_year, --exit_spinup).

  • --tempdir, --options_log_json: Not exposed.

  • Ensemble post-processing (--postproc_file): Not shown. Must be added manually to manage_ensemble.py invocations outside the GUI.

  • Multi-site runs use implicit case_copy.py logic but do not expose per-site rebuild control.

Machine detection:

The GUI infers the machine from hostname (lines 874–883):

  • or-condo: sets --machine cades

  • eos / titan: sets machine and paths for ORNL Titan (deprecated)

  • Otherwise: defaults to --machine oic2 (custom machine; may require manual config_machines.xml setup)

Hardcoded paths:

  • Default rundir on CADES: /lustre/or-hydra/cades-ccsi/scratch/<user>

  • Default ccsm_input on CADES: /lustre/or-hydra/cades-ccsi/proj-shared/project_acme/ACME_inputdata/

  • Emacs as the file viewer (line 695)

Command-line flexibility:

For production workflows, the command-line interface (site_fullrun.py) is recommended — it exposes the full range of flags, supports scriptable invocation, and avoids the GUI’s hostname-dependent defaults.

Related scripts:

  • site_fullrun.py: The main orchestrator invoked by the GUI.

  • plotcase.py: Plotting utility (not part of the standard OLMT distribution; verify availability before using the plot features).