Mapping file algorithms and naming convention

Proposed naming convention for E3SM V2 and newer compsets:

map_grida_to_gridb_Optionaltext.ToolAlgorithm.YYYYMMDD.nc

Where grida and gridb are existing grid naming conventions established by the respective component.

“Optionaltext” can be any additional text you want to help identify the mapping file.

The name can only use letters, numbers, “_” and “.”

Here we propose to standardize the suffix to denote the Tool and Algorithm (Following recommendation from @Charlie Zender for ncremap) :

Tool:

• esmf: Earth System Modeling Framework

• nco: NCO (ncremap can generate aave maps, and also serve as a frontend to esmf and tr/mbtr)

• tr: TempestRemap

• mbtr: MOAB-TempestRemap

• cstm: A custom tool (such as used for river to ocean maps)

FV to FV Algorithms: (used in E3SMv2 and higher)

• aave: Maps which compute a common refinement (intersection) mesh and then integrate a piecewise-constant reconstruction.

  • can be produced by: ESMF, NCO and TR/MBTR

  • pros: conservative, montonone, cell averaging good for fine-to-coarse maps.

  • cons: 1st order accurate, not suitable for coarse-to-fine maps (blocky results)

  • examples: esmfaave, ncoaave, traave. Usage with ncremap:

    • ncremap -s grd_src.nc -g grd_dst.nc -a ncoaave -m map_grida_to_gridb_ncoaave.YYYYMMDD.nc

    • ncremap -s grd_src.nc -g grd_dst.nc -a esmfaave -m map_grida_to_gridb_esmfaave.YYYYMMDD.nc

    • ncremap -s grd_src.nc -g grd_dst.nc -a traave -m map_grida_to_gridb_traave.YYYYMMDD.nc

       

• bilin: bilinear interpolation

  • can be produced by: ESMF, TR/MBTR

    • ESMF: ESMF_RegridWeightGen -s srcmesh.nc -d dstmesh.nc -w mapfile.nc --method bilinear --extrap_method nearestidavg

    • TempestRemap:

      1. GenerateOfflineMap --a srcmesh.nc --b dstmesh.nc --out ov_mesh.nc --allow_no_overlap

      2. GenerateOfflineMap --in_mesh srcmesh.nc --out_mesh dstmesh.nc --ov_mesh ov_mesh.nc --in_type fv --out_type fv --method bilin --out_map mapfile.nc

    • mbtempest: mbtempest --type 5 --load srcmesh.nc --load dstmesh.nc --intx intersection_mesh.h5m --weights --method fv --method fv --order 1 --order 1 --fvmethod bilin --file mapfile.nc

  • pros: monotone, 2nd order accurate

  • cons: non-conservative. not suitable for fine-to-coarse maps (aliasing errors)

  • examples: esmfbilin, trbilin

• patch: patch based algorithm (L2 projection?).

  • can be produced by: ESMF only

  • pros: accurate. good for coarse-to-fine maps. not sure how it performance on fine-to-coarse maps.

  • cons: can have small non-monotone weights

  • examples: esmfpatch

• intbilin: Integrated bilinear or barycentric (TR/MBTR only)

  • can be produced by: TR, MBTR only.

  • pros: monotone, 2nd order, good for fine-to-coarse and coarse-to-fine maps.

  • cons: TR software may have some issues when source grid has holes.

  • examples: trintbilin, mbtrintbilin

  • trintbilin: Pass --method intbilin option to TempestRemap’s GenerateOfflineMap

  • mbtrintbilin: Pass --fvmethod intbilin option to mbtempest

• fv2 (or fvnp2): 2nd order FV reconstruction, cell integrated on target grid (TR/MBTR only)

  • pros: 2nd order, conservative

  • cons: not monotone

  • monotone via new E3SM v3 coupler’s nonlinear fixer https://acme-climate.atlassian.net/wiki/spaces/COM/pages/3771301899

  • examples: trfv2

• custmnn: custom nearest neighbor

  • used with river runoff maps (r2o).

  • examples:

• neareststod/nearestdtos: nearest source to destination or nearest destination to source

  • Can be produced by: EMSF only

  • Pros: For the case where 2 meshes may not overlap but need to couple. From the ESMF docs. “The nearest neighbor interpolation options work by associating a point in one set with the closest point in another set. If two points are equally close then the point with the smallest index is arbitrarily used (i.e. the point with that would have the smallest index in the weight matrix). There are two versions of this type of interpolation available in the regrid weight generation application. One of these is the nearest source to destination method ("-m neareststod"). In this method each destination point is mapped to the closest source point. The other of these is the nearest destination to source method ("-m nearestdtos"). In this method each source point is mapped to the closest destination point. Note, that with this method the unmapped destination point detection doesn't work, so no error will be returned even if there destination points which don't map to any source point.”

  • examples: esmfnearestdtos

Examples:

Suffix = esmfaave, esmfbilin, ncoaave, trmono, trmonotrn, trintbilin, trhighorder, mbtrmono, cstmnn ...

SE to/from FV Algorithms: (no longer used by E3SM, but used for some analysis tasks)

• mono: TR developed algorithms which use a spectral element with monotone basis functions. The degrees of freedom for the basis function (“np”) is usually denoted in the grid name, such as ne30np4. For FV grids, only np=1 is supported.

  • can be produced by: TR only

  • monoSE2FV: SE monotonic basis reconstruction integrated over FV (np=1) cells

  • monoSE2SE: projection between source and target grid monotonic reconstructions

  • monoFV2SE: does this exist?

  • pros: conservative, monotone, good for fine-to-coarse maps.

  • cons: 1st order accurate

  • coarse-to-fine maps? Probably good, except for FV source grids.

• intbilin: Integrated bilinear vi TR’s “mono2” option. For finite element grids, the shape functions are replaced by a piecewise linear shape functions which are then integrated using a common refinement mesh

  • can be produced by: TR only

  • pros: monotone, 2nd order, good for fine-to-coarse and coarse-to-fine maps.

  • cons: SE2FV only.

• highorder: Use of SE shape functions or higher order FV for reconstruction, projected onto SE shape functions, or integrated over FV cell (np=1)

  • The most accurate SE2SE and SE2FV maps.

  • Currently not recommended due to large negative weights

• {algorithm}trn: For any map from gridA to gridB, one can compute an area weighted transpose map from gridB to gradA. In general, the transpose map will not preserve the properties of the original map. However, the transpose of a consistent map will be conservative and the transpose of a conservative map will be consistent. The transpose of the SE->FV “mono” map (monotone and conservative) will be monotone and conservative.

Historical usage:

_aave.nc:        ESMF conservative/monotone "area averaged" maps. NOW: esmfaave
_bilin.nc:       ESMF bilinear NOW: esmfbilin
_mono.nc       TempestRemap conservative, monotone map NOW: “mono” is reserved for when the source is an SE grid. When its FV (as in ne30pg), use traave.
_highorder.nc TempestRemap high-order, conservative, non-monotone  ( several TR options in this category )
_intbilin.nc       TempestRemap integrated bilinear:   monotone, non-conservative
_monotr.nc     TempestRemap transpose of a mono map.  
_highordertr.nc   TempestRemap transpose of a highorder map.  (not recommended) 

_conserve.nc. Used for a short time for TR conservative, high-order, non-monotone maps. Confusing since "conserve" implies it's a replacement for an "aave" type map, when really that type of map is a replacement for "bilin".