This page is devoted to instruction in ncremap. It describes steps necessary to create grids, and to regrid datasets between different grids with ncremap. Some of the simpler regridding options supported by ncclimo are also described at Generate, Regrid, and Split Climatologies (climo files) with ncclimo. This page describes those features in more detail, and other, more boutique features often useful for custom regridding solutions.
The Zen of Regridding
Most modern climate/weather-related research requires a regridding step in its workflow. The plethora of geometric and spectral grids on which model and observational data are stored ensures that regridding is usually necessary to scientific insight, especially the focused and variable resolution studies that E3SM models conduct. Why does such a common procedure seem so complex? Because a mind-boggling number of options are required to support advanced regridding features that many users never need. To defer that complexity, this HOWTO begins with solutions to the prototypical regridding problem, without mentioning any other options. It demonstrates how to solve that problem simply, including the minimal software installation required. Then we solve the same simple problem in more powerful (workflow-oriented, parallel) ways. Once the basic regridding vocabulary has been introduced, this HOWTO doubles-back to explain how to solve the prototype problem when one or more inputs are "missing", or need to be created. The HOWTO ends with descriptions of regridding workflows that use features customized to particular models, observational datasets, and formats.
Software Requirements:
At a minimum, install a recent version NCO on your executable $PATH with the corresponding library on your $LD_LIBRARY_PATH. NCO installation instructions are here (fxm: link). We highly recommend installing NCO through the Conda package. That will automatically install another important piece of the regridding toolchain, the ESMF_RegridWeightGen (aka ERWG) executable. Execute 'ncremap --config' to verify you have a working installation:
zender@aerosol:~$ ncremap --config
ncremap, the NCO regridder and map- and grid-generator, version 4.7.6-alpha03
...[Legal Stuff]...
Config: ncremap running from directory /Users/zender/bin
Config: Calling NCO binaries in directory /Users/zender/bin
Config: Binaries linked to netCDF library version 4.4.1.1
Config: No hardcoded path/module overrides
Config: ESMF weight-generation command ESMF_RegridWeightGen found as /opt/local/bin/ESMF_RegridWeightGen
Config: Tempest weight-generation command GenerateOfflineMap found as /usr/local/bin/GenerateOfflineMap
Only NCO is required for basic ncremap operation. To create new mapfile you will want ERWG. TempestRemap is not yet available in a pre-packaged format and must be built from scratch. It is only required for power-users. Make sure ncremap reports a sufficiently working status as above before proceeding further.
The Prototype Regridding Problem:
The regridding problem most commonly faced is converting output from a standard resolution model simulation to equivalent data on a different grid for visualization or intercomparison with other data. The EAM v1 model low-resolution simulations are performed and output on the ne30np4 SE (spectral element) grid, aka the "source grid". Data on this source grid have only one horizontal dimension (i.e., 1D) which makes them difficult to visualize. The recommended (fxm: link) 2D grid for analysis of these simulations is the 129x256 FV (finite-volume) grid, aka the "destination grid". The single most important capability of a regridder is the intelligent application of weights that transform data on the input grid to the desired output grid. These weights are stored in a "map-file", a single file that contains all the necessary weights and grid information necessary. Most regridding problems revolve around creating the appropriate map-file. This prototype problem is well-trod ground, so the appropriate map-file (map.nc) already exists (fxm: link) and ncremap can immediately transform the input dataset (dat_src.nc) to the output dataset (dat_dst.nc):
ncremap -m map.nc dat_src.nc dat_dst.nc
This solution is deceptively simple because it conceals the choices, paths, and options required to create the appropriate map.nc for all situations. We will discuss creating map.nc later after showing more powerful and parallel ways to solve the prototype problem. For now, note that the solution above only works for users savvy enough to know how to find appropriate pre-built map-files. E3SM map-files are available here (fxm: link). At most DOE High Performance Computing (HPC) centers these can also be found in my (Charlie Zender's) directory as ~zender/data/maps. Take a minute now to look there.
Pre-built map-files use the (nearly) standardized naming convention map_srcgrd_to_dstgrd_algtyp.YYYYMMDD.nc, where srcgrd and dstgrd are the source and destination grid names, algtyp is a shorthand for the numerical regridding algorithm, and YYYYMMDD is the date the map was created. The source grid in the example above is called ne30np4, the destination is called fv129x256. The only pre-built map for this combination is map.nc = map_ne30np4_to_fv129x256_aave.20150901.nc. What is "aave"? Weight generators can use about a dozen interpolation algorithms for regridding, and each has a shorthand name. For now, it is enough to know that the two most common algorithms are (first-order) conservative area-average regridding ("aave") and bilinear interpolation ("bilin" or "blin"). Hence this conservatively regrids dat_src.nc to dat_dst.nc with first order accuracy:
ncremap -m map_ne30np4_to_fv129x256_aave.20150901.nc dat_src.nc dat_dst.nc
The simplest regridding procedure applies an existing map-file to your data, as in the above example. If the desired map-file cannot be found, then you must create it. Creating a map-file requires a complete specification of both source and destination grids. The files that contain these grid specifications are called "grid-files". E3SM grid-files are available here (fxm: link). At most DOE High Performance Computing (HPC) centers these can also be found in my (@czender's) directory as ~zender/data/grids. Take a minute now to look there for the prototype problem grid-files, i.e., for FV 129x256 and ne30np4 grid-files.
You might find multiple grid-files that contain the string "129x256". Grid-file names are often ambiguous. The grid-file metadata (ncks -M grid.nc) often displays the source of the grid. The metadata, and sometimes the data itself, are usually better in files with a YYYYMMDD-format date-stamp. When grids appear to be identical except for the date-stamp, use the one with the later date-stamp. The metadata in file 129x256_SCRIP.20150901.nc clearly state it is an FV grid and not some other type of grid with 129x256 resolution.
Likewise multiple grid-files contain the string ne30. The different SE and FV grid types are shown with figures and described here (https://acme-climate.atlassian.net/wiki/spaces/Docs/pages/34113147/Atmosphere+Grids). Currently, most people will want the "dual-grid" with the pentagon options. The correct grid-file for this is ne30np4_pentagons.091226.nc.
Once armed with the correct source and destination grid-files, one can generate the map-file with
ncremap -s grd_src.nc -g grd_dst.nc -m map.nc
which for the prototype problem would look like
ncremap -s ne30np4_pentagons.091226.nc -g 129x256_SCRIP.20150901.nc -m map_ne30np4_to_fv129x256_aave.YYYYMMDD.nc
Save the resulting map-file map.nc and use it for your future regridding between those grids. Generating map-files is much more computationally expensive than regridding, i.e., than applying the weights in the map-file to the data. We have glossed over the many options that weight-generators will take into consideration, because their default values are often good-enough.
Intermediate Regridding:
Intermediate regridding divides into four cases:
...
Advanced Feature #1:
Regridding Regional EAM/CAM-SE Output
CAM will produce regional output requested with the finclNlonlat namelist parameter. These regional output files are in a special format that we call RRG (for "regional regridding"). There can be any number of regions in a single RRG file, however all regions must be rectangular in latitude/longitude. ncremap can easily regrid RRG output from an FV-dycore easily because ncremap can infer the regional grid from any FV data file. This example demonstrates how to regrid regional SE output. This is crucial for efficiently conducting regional process studies with EAM. Multiple reasons make regridding SE RRG data difficult.
1. SE grids have well-defined weights not vertices for each gridpoint
2. Grid generation software (ESMF and TempestRemap) currently only create global not regional SE grid files
3. RRG files contain only SE gridcell center locations, not weights
The RRG file format requires handling two other difficulties, shared by FV and SE data, prior to regridding:
1. Non-standard variable names and dimension names
2. Regional files can contain multiple regions
ncremap requires at least two and up to six additional input arguments for RRG regridding.
Advanced Feature #2: