sima0_13_002: Refactor vertical coordinate computation in MPAS dynamical core

[kuanchihwang]

Tag name (required for release branches):

sima0_13_002

Originator(s):

kuanchihwang

Descriptions (include the issue title, and the keyword ['closes', 'fixes', 'resolves'] followed by the issue number):

MPAS dynamical core uses height, denoted by $\zeta$, as the vertical coordinate system. In CAM-SIMA, the coordinate values are computed in the interface layer of MPAS dynamical core for history and physics initialization.

However, it can be argued that the vertical coordinate system should be considered an implementation detail of MPAS dynamical core, and that it should not concern CAM-SIMA. See Appendix "C.2 Vertical grid" in MPAS user guide for more information.

This PR refactors and relocates vertical coordinate computation to the subdriver layer of MPAS dynamical core. Now, CAM-SIMA just calls the appropriate procedures to get the coordinate values. Unit tests are added to ensure correctness.

This PR also ports a fix from CAM (ESCOMP/CAM#1095) to limit longitude values within the range of $[0, 2 \pi)$ according to MPAS mesh specifications.

Describe any changes made to the build system:

None

Describe any changes made to the namelist:

None

List any changes to the defaults for the input datasets (e.g., boundary datasets):

None

List all files eliminated and why:

None

List all files added and what they do:

None

List all existing files that have been modified, and describe the changes:

M       src/dynamics/mpas/driver/dyn_mpas_procedures.F90
  * Implement standardized procedures for computing vertical coordinates
M       src/dynamics/mpas/driver/dyn_mpas_subdriver.F90
  * Allow selective queries to mesh dimensions
  * Limit longitude values within the range of [0, 2 * pi)
M       src/dynamics/mpas/dyn_grid_impl.F90
  * Refactor reference height computation in terms of standardized procedures
M       src/dynamics/mpas/tests/unit/test_dyn_mpas_procedures.pf
  * Implement unit tests

Regression tests:

SMS_Ln9.mpasa480_mpasa480.FKESSLER.derecho_gnu.cam-outfrq_kessler_mpas_derecho (Overall: DIFF)
SMS_Ln9.mpasa480_mpasa480.FKESSLER.derecho_intel.cam-outfrq_kessler_mpas_derecho (Overall: DIFF)

Round-off errors due to limiting longitude values within the range of $[0, 2 \pi)$.

SMS_Ln9.ne3pg3_ne3pg3_mg37.FADIAB.derecho_gnu.cam-outfrq_se_cslam (Overall: FAIL)
SMS_Ln9.ne3pg3_ne3pg3_mg37.FKESSLER.derecho_intel.cam-outfrq_se_cslam_multitape (Overall: NLFAIL)

Known failing tests.

[nusbaume]

Thanks @kuanchihwang!

[jimmielin]

Thanks @kuanchihwang! The PR looks good to me, I have two optional changes for your consideration.

[jimmielin]

This is a nitpick but maybe the cumulative sum could be constructed through the loop instead of calling sum for each k

Suggested change

	do k = 1, size(zw)
	zw(k) = sum(dzw(1:k - 1))
	end do
	zw(1) = 0.0_real32
	do k = 2, size(zw)
	zw(k) = zw(k - 1) + dzw(k - 1)
	end do

same for the real64 variant. I think either construction is clear in intent and the performance difference would be minimal, so please feel free to ignore this.

[kuanchihwang]

The suggested form of loop introduces read-after-write (RAW) dependency, which prevents vectorization. Intel compiler gives the following remark:

remark #15344: Loop was not vectorized: vector dependence prevents vectorization

However, I agree that the loop trip count is likely never large enough for this to matter.

[jimmielin]

Thanks for testing! Sounds good.

[jimmielin]

This looks good, I wonder if making the dzw have more realistic numbers (not whole numbers, e.g., 55.1, 101.2, 202.3) would better exercise the ULP tolerance?

[kuanchihwang]

Unit tests can be seen as a form of code documentation. I chose whole numbers here because they are easier to grasp for humans. People can just glance at the code and quickly understand what it is supposed to do without a calculator in hand.