Generalize QuickView for ELM and more

[huiwanpnnl]

My colleague Gautam Bisht (who is the PI of the BER SciDAC-5 river dycore project and a co-lead of E3SM's land group) expressed interest in using QuickView to inspect data files related to the E3SM land model, ELM. After some initial discussions, the two of us thought the first (and very helpful) step would be to update the Reader in QuickView so that it can parse ELM data files that are using the ne*pg2 meshes which QuickView is already supporting for EAM. Gautam provided two data files on the ne4pg2 mesh, both of which can be found through NERSC's web portal:

• SMS_Lm1.ne4pg2_ne4pg2.IELM.pm-cpu_intel.20250929_150033_ww4ivg.elm.h0.0001-01.nc is a simulation output file (history file) from ELM.
• surfdata_ne4pg2_simyr2000_c190620_with_TOP.nc, if I understood correctly, is an input file for ELM simulations.

After some trial and error, I was able to use QuickView to show some of the variables in the output file SMS_Lm1.ne4pg2_ne4pg2.IELM.pm-cpu_intel.20250929_150033_ww4ivg.elm.h0.0001-01.nc after playing two tricks:

1. Rename the dimension lndgrid to ncol.
2. Add EAM's vertical coordinate variables lev and ilev.

The script I used (kludge.bash), EAM's vertical coordinate variable data (lev_ilev_L80.nc), the revised ELM output file (test_elm_ncol_lev_ilev.h0.0001-01.nc), and the ne4pg2 connectivity file can be found here.

This exercise made me realize not only that QuickView is hardwired to the dimension name ncol, but also (1) it currently only visualizes arrays with a time dimension, and (2) it requires lev or ilev to be present in the data file. In order to make QuickView more general/flexible and hence support ELM as well as a larger variety of files and variables related to EAM, I would like to propose two changes: one for the Reader, and one for the UI, as detailed below.

[huiwanpnnl]

1. Proposed change to the Reader

While continuing to assume the connectivity file has a dimension named grid_size, use the size of that dimension (e.g., 384 for ne4pg2) to identify the dimension in the data file that corresponds to the horizontal mesh (e.g., ncol in EAM files, lndgrid in ELM output, and gridcell in Gautam's surface data file.

Identify all variables in the data file that have the horizontal dimension, regardless of how many dimensions these variable have.

Examples from EAM and EAMxx output files, where the dimension name for the horizontal mesh is ncol:

double area(ncol) ;
float CCN3(time, lev, ncol) ;
float p_int(time, ncol, ilev) ;
float BURDEN1(time, ncol) ;
float CLD_CAL_LIQ(time, cosp_ht, ncol) ;
float RFL_PARASOL(time, cosp_sza, ncol) ;
float CLD_MISR(time, cosp_htmisr, cosp_tau, ncol) ;
float CLMODIS(time, cosp_prs, cosp_tau_modis, ncol) ;
float CLRIMODIS(time, cosp_reffice, cosp_tau_modis, ncol) ;
float CLRLMODIS(time, cosp_reffliq, cosp_tau_modis, ncol) ;

Examples from ELM output, where the dimension name for the horizontal mesh is lndgrid:

float topo(lndgrid) ;
float ZSOI(levgrnd, lndgrid) ;
float H2OSNO_TOP(time, lndgrid) ;
float H2OSOI(time, levgrnd, lndgrid) ;
float TLAKE(time, levlak, lndgrid) ;
float QSNOMELT_LYR(time, levsno, lndgrid) ;

Examples from the surface data file, where the dimension name for the horizontal mesh is gridcell:

double PCT_SAND(nlevsoi, gridcell) ;
double LANDFRAC_PFT(gridcell) ;
double PCT_NAT_PFT(natpft, gridcell) ;
double MONTHLY_LAI(time, lsmpft, gridcell) ;
double CANYON_HWR(numurbl, gridcell) ;
double ALB_IMPROAD_DIR(numrad, numurbl, gridcell) ;
double TK_ROOF(nlevurb, numurbl, gridcell) ;

[huiwanpnnl]

2. Proposed change(s) to the UI

Let me use the phrase "the other dimensions" to refer to the dimensions that do not have the same size as grid_size in the connectivity file but nevertheless are dimensions of at least one variable that has a horizontal dimension. In the control panel of the UI, it would be useful to have one slider for each of these "other" dimensions.

I would also propose reorganizing the control panel: instead of the 5 sections currently offered, it might be useful to have the following:

1. "Horizontal Dimension": This section would contain the longitude and latitude sliders and the drop-down menu for map projection. On our (user's) wish list is also the option to specify the center longitude of the map.
2. "Other Dimensions": This section would contain one slider for each of the "other" dimensions.
3. "Variables": We could have a single list, but offer two search boxes:
   • Search by name, as currently offered;
   • Search by dimension name. For example, if a user types in lev, present a filtered list of all variables that have the lev dimension.

Also, when variables are listed in section 3, it would be useful to have the dimensions in addition to the variable names, e.g., CCN3(time, lev, ncol).

[huiwanpnnl]

@kaizhangpnl, please chime in from the user's perspective.

[huiwanpnnl]

Sebastien (@jourdain) and Berk (@berkgeveci), do those make sense to you? I'd be happy to discuss further. Thanks a lot!