bug fix: PEATCLSM water table depth

[gmao-rreichle]

The water table depth (WATERTABLED) export variable ("zbar" in Catchment) that was introduced with PEATCLSM (#524) produces inappropriate values for mineral tiles.

This PR restricts the calculation of the WATERTABLED and FSWCHANGE exports to PEATCLSM tiles and assigns MAPL_UNDEF elsewhere. The PR also renames these exports for clarity and consistency:

WATERTABLED --> PEATCLSM_WATERLEVEL
FSWCHANGE   --> PEATCLSM_FSWCHANGE

Moreover, the sign convention for PEATCLSM_WATERLEVEL was flipped from that of WATERTABLED so that now water level is negative below ground and positive above ground.

One open question (probably for @weiyuan-jiang or @mathomp4):
The above PEATCLSM exports are calculated in tile space and remapped to the atmospheric grid via MAPL Location Stream, along with all other tile-space land exports. Since PEATCLSM tiles are still "land" tiles (i.e., type 100) and are identified only by their uniquely large porosity (POROS) values, the question is how no-data-values (MAPL_UNDEF) are treated in the remapping from tile to grid. The desired behavior is to ignore MAPL_UNDEF in the tile2grid operation. That is, if a given (say, cube-sphere) grid cell includes two tiles, one mineral and one PEATCLSM, then the average of PEATCLSM_WATERLEVEL for the cube-sphere grid cell in question should be that of the PEATCLSM tile, rather than MAPL_UNDEF. If this is not the default behavior, are there options in MAPL Location Stream to make this happen?

Since the PR only touches exports that are only used for the forthcoming SMAP L4_SM version, it should be trivially 0-diff for the GCM. Given the extent of the edits, though, I chose the regular 0-diff label to be safe.

There is some urgency to this bug fix because it is needed for L4_SM Version 7 production, which is estimated to start later this month.

A matching GEOSldas PR will be created.

The revised variable names and documentation are not set in stone. Feel free to comment if you have any questions or suggestions.

cc: @gmao-jkolassa @rdkoster @sdrabenh @biljanaorescanin @mbechtold @gmao-qliu

[weiyuan-jiang]

I think in MAPL, the data MAPL_UNDEF is ignored and is not counted in averaging calculation

[weiyuan-jiang]

That is, if a given (say, cube-sphere) grid cell includes two tiles, one mineral and one PEATCLSM, then the average of PEATCLSM_WATERLEVEL for the cube-sphere grid cell in question should be that of the PEATCLSM tile, rather than MAPL_UNDEF.

DO you mean the calculation of PEATCLSM_WATERLEVEL should depend on other variables PEATCLSM ?

[gmao-rreichle]

I think in MAPL, the data MAPL_UNDEF is ignored and is not counted in averaging calculation

Ok, thanks. We'll assume for now that nothing else needs to be done and verify the assumption in a cube-sphere tile-space experiment.

DO you mean the calculation of PEATCLSM_WATERLEVEL should depend on other variables PEATCLSM ?

No. Water level is computed in tile space in CatchGridComp. The question is simply what we get when we ouput waterlevel in grid space from SurfaceGridComp (where the tile2grid aggregation is done by MAPL Location stream). So if x(tile1) = 0.5 and x(tile2)=NaN, we want x(gridcellA)=0.5, where gridcellA consists of tile1 and tile2.

[bena-nasa]

@gmao-rreichle If x(tile1) = 0.5 and x(tile2)=NaN, where gridcellA consists of tile1 and tile2. Then the MAPL_LocstreamTransoform will give: x(gridcellA)=0.5

Basically any MAPL_UNDEF in the source tiles does not count towards the destination cell. In that case the weights are renormalized. That is done here:
https://github.com/GEOS-ESM/MAPL/blob/main/base/MAPL_LocStreamMod.F90#L1949

[mbechtold]

No questions or suggestions. Sounds like a very good idea to me to have PEATCLSM_WATERLEVEL and PEATCLSM_FSWCHANGE output variables. I also appreciate the sign change.

[gmao-rreichle]

See below for update on testing.

@sdrabenh: We are ready to start SMAP L4_SM Version 7 reprocessing as soon as we have a new GEOSgcm_GridComp release that includes this bug fix. The PR could be merged immediately, so we could start L4_SM reprocessing without further delay. Or we could wait (probably about a day) for Biljana's test to be completed. In any case, this is a heads-up that it would be very helpful to merge this PR as soon as you can fit it into your schedule.

I'm going to change the status from "draft" to "ready for review" now so we can start collecting approvals from @GEOS-ESM/landice-team and @GEOS-ESM/ocean-team. The changes are strictly limited to export variables for "land" tiles and can be considered trivially 0-diff for all things GCM.

Update on tests completed so far:
From @gmao-qliu, 13 Jun 2022: "The NRv10 and OLv7 tests are both zero diff from before. I also confirm that the WATERABLED and FSWCHANGE output are scientifically identical for peat tiles (with WTD sign reversed)."
From @biljanaorescanin, 13 Jun 2022: "I've run AGCM tests and those are zero diff."
Qing's testing of the changes in the PEATCLSM_* outputs was done on the EASEv2 grid, with 1 tile per grid cell, which is all we need for SMAP L4_SM. We still need to verify that that the tile2grid aggregation works as expected when on the cube-sphere tile space with lat/lon-gridded output. @biljanaorescanin is working on this. Based on the input by @bena-nasa above, we fully expect this to work properly. But any issues there would not affect SMAP L4_SM.

[gmao-rreichle]

FINAL update: Based on output created by @biljanaorescanin using "develop" and this branch with NLv5 bcs on the cube-sphere tile space, I verified that PEATCLSM_WATERLEVEL and PEATCLSM_FSWCHANGE are ok. PR is definitely ready to be merged as is.