Updates xesmf docs

[jasonb5]

Description

This PR updates the documentation for xESMF regridder.

• Closes [Doc]: Update horizontal docs to outline how xCDAT extends xESMF #421

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• My changes generate no new warnings
• Any dependent changes have been merged and published in downstream modules

If applicable:

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass with my changes (locally and CI/CD build)
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have noted that this is a breaking change for a major release (fix or feature that would cause existing functionality to not work as expected)

[codecov-commenter]

Codecov Report

Patch and project coverage have no change.

Comparison is base (5790bc9) 100.00% compared to head (312aa47) 100.00%.

📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #432   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           14        14           
  Lines         1308      1308           
=========================================
  Hits          1308      1308           

Impacted Files	Coverage Δ
xcdat/regridder/accessor.py	100.00% <ø> (ø)
xcdat/regridder/xesmf.py	100.00% <ø> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[jasonb5]

@pochedls @lee1043 @chengzhuzhang @tomvothecoder
Does anyone remember the difference between regrid2 and esmf? I recall it had to do with regrid2 treating the grid as flat but I can't remember any of the details.

[pochedls]

@pochedls @lee1043 @chengzhuzhang @tomvothecoder Does anyone remember the difference between regrid2 and esmf? I recall it had to do with regrid2 treating the grid as flat but I can't remember any of the details.

@taylor13 - Is there a concise summary of regrid2 (for code docstrings)? It looks like CDAT had:

To perform all the tasks required to regrid the input data into the ouput data in the latitude-level plane for all times

If I remember correctly, ESMF does not treat grid cell latitude bounds as constant in longitude and regrid2 does this? Is there a situation where a user would definitely want to use regrid2 over ESMF?

[taylor13]

Yes, your recall is essentially correct. As described here, ESMF assumes the vertices of grid cells are connected by great circles (which is inconsistent with most model latxlon grids). regrid2, on the other hand, assumes that the vertices are connected by lines of longitude or lines of latitude (consistent with models). So regrid2 is more accurate in regridding from one latxlon grid to another latxlon grid. [All of this discussion applies to conservative regridding.]

regrid2, however, can only handle latxlon grids and does not offer the variety of regridding methods that ESMF does. regrid2 is restricted to the conservative regridding method.

For moderate to high resolution latxlon grids, the distortions found in the ESMF conservatively regridded fields may be negligible, but for coarser grids they may not always be. If a conservative regridding algorithm does not correctly reconstruct grid cell shapes, "adjustments" must be made to maintain conservation, which are not strictly local, so this effectively disperses the quantity being conserved elsewhere (though usual by an amount that is negligible).

The main case where regrid2 offers a distinct advantage is when the target grid is quite coarse. Consider, for example, computing zonal means across ocean basins. You can do this by masking the land values on the original grid and then regridding to a target grid of desired latitude width and cells that span the entire ocean basin longitudinally.

The reason ESMF cells give incorrect values is that each cell spanning the ocean basin arcs toward the pole in the middle of the basin (following a great circle). So the zonal mean in this case is actually getting contributions from higher latitudes in the middle of the basin than it is at the edges.

For further information about the original fortran code, which was translated into C as regrid2 see sections 2.3, 2.4, and 3.7 of the EzGet documentation. The area-averaging example of section 2.4 shows how regridding can be used to compute an area-mean over N. America.

[jasonb5]

@taylor13 Thanks so much for all the great info.

[tomvothecoder]

Hi @jasonb5, I made one minor edit which is noted in my PR review comment. Everything looks good. Thanks!