Map file analysis

The page documents two python utilities to analyze E3SM map files. It checks the the key properties that can be examined by NCO (ncks --checkmaps), and several additional properties, including consistency with the land/ocean fractions induced by the flux maps.

Analyze single E3SM mapping file:

From https://github.com/mt5555/remap-ncl , one needs “mfa.py”, “test_fields.py” and (optionally, for map error plots) “polyplot_hv.py”. To run the code, one needs to specify the mapfile type (o2a, a2o, l2a, etc…), the mapfile name, the flux map name (needed to compute land/ocean partial cell fractions) and the domain.lnd file (needed to determine lfrin for the case).

Running the code on the l2a map map_r0125_to_ne256pg2_bilin.200212.nc, which is known to produce problems in E3SM simulations, we get:

% usage: ./mfa.py map_type map_file_name.nc    [o2a_flux_map.nc] [domain.lnd.nc]
% map_type=a2o, o2a, a2l, l2a, g2g
% ocean->atm flux map (needed for a2o, o2a and l2a maps)
% domain land file (land fraction, needed for l2a maps


python mfa.py l2a \
/lcrc/group/e3sm/data/inputdata/cpl/gridmaps/ne256pg2/map_r0125_to_ne256pg2_bilin.200212.nc \
/lcrc/group/e3sm/data/inputdata/cpl/gridmaps/ne256pg2/map_oRRS18to6v3_to_ne256pg2_nco.200212.nc 
/lcrc/group/e3sm/data/inputdata/share/domains/domain.lnd.r0125_oRRS18to6v3.200212.nc

% output:
src grid (bad area)  n_a=4147200
dst grid dx   min=16.47km max=19.57km area/4pi=1.000 n_b=1572864
o2a flux map: n_a=3693225 n_b=1572864
land domain file: n_a=4147200
map weights:     min,max=0.0000000000000 0.9918838095466
rowsums          min/max=1.0000000000000 1.0000000000000
skipping colsums due to bad area data
zeroset-fraction     max=0.2970986902642 (990 cells have err>.001)
Y16_32 pointwise relative error, full cells:     l2=1.708e-05  max=6.337e-05
Y16_32 pointwise relative error, partial cells:  l2=1.327e-03  max=1.128e-02

For this map, the weights are good (all between 0 and 1), the rowsums are good. The colsums are not computed because “bilin” maps often dont include the needed cell area. The L2 and max errors are quite low for full land cells (and significantly larger over partial land cells, as expected). The problem with this map is the “zeroset-fraction”: there are 990 partial land cells on the atmosphere grid that dont get any data from the land model with this map. The largest land fraction over such cells in 0.29, resulting in a 29% error in the surface temperature on the atmosphere grid.

Analyze entire E3SM case:

The second utillity will examine all mapping files from a working E3SM case by parsing the XML files after running ./case.setup. It produces a latex file, which can then be processed into a PDF report. The report starts with one page for each unique grid, with some mesh size metrics, a plot of the grid and a plot of the analytic test function (spherical harmonic Y16,32) used to compute map file errors. The report then gives one page for each unique map file, with map algorithm statistics (min and max weights, row sums (consistency) and column sums (conservation)) as well as the L2 and max errors for mapping our test function. For non-global maps (i.e. ocean->atmsphere), the errors are given over the full range of the map (including coastal regions with partial land/ocean fractions) and over the subdomain of 100% land or ocean points (where the maps usually perform better). The map file pages list the important characteristics that should be checked for each map including metrics for conservation, consistency and monotonicity. For ocean maps, plots are included to verify the above properties hold over ocean points and remain well behaved in coastal regions.

This was a 2023 summer intern project (Dallin Seyfrield ( BYU ), Drew Sukova (Purdue), Mark Taylor ). Funded by the E3SM ECP project. For code and instructions on how to run, see the README file in: https://github.com/E3SM-Project/PreAndPostProcessingScripts/tree/master/regridding/map_file_analysis

Some highlights:

• Found the root cause of the “speckling” problem in the ne256 trigrid setup reported here: /wiki/spaces/NGDNA/pages/3597565953 This problem is due to the land->atmosphere state map being inconsistent with the land franction on the atmosphere grid. In particular, the map does not provide data in a few grids points where the land fraction is .30. At such a point, the atmosphere field is 30% land + 70% ocean, and since land will send no data, this results in temperature at a single point being consistently 30% too low. This is reported in the metric for “land frac consistency error” given in the page for the lnd2atm state map.

• Uses the python “holoviews” package which can directly plot unstructured grid data (by shading each polygon cell) manytimes faster than matplotlib’s ‘polycollection’ approach.

• The E3SM v3 trigrid setups have a small (but larger than expected) discrepancy between the land fraction computed from ocn->atm (computed from ocn2atm map) and ocn->lnd->atm (computed from domain.lnd + lnd2atm map). The metric for this is the “land frac consistency error” given in the page for the lnd2atm flux map. Andrew Bradley identified a likely source of this error, which is the default fminval=.001 in gen_domain. Land cells with a land fraction less than fminval are removed (land mask=0). For tri-grid we may want to consider lowering fminval, so that there are more land points and thus more likely that the lnd->atm map will provide data on all partial land atmopshere cells.