Add HYBRID_3D and HYBRID_MAP options to ALE_COORDINATE_CONFIG

[awallcraft]

Add two options to ALE_COORDINATE_CONFIG that are like HYBRID, but supporting spatially varying target densities and ALE resolutions (thicknesses).

The fully general interface is ALE_COORDINATE_CONFIG=HYBRID_3D which is like HYBRID except that the netCDF variables (e.g. sigma2 and dz) are 3D fields (x-y-z). Like HYBRID, the 2nd variable (e.g. dz) can be replaced by a FNC1 string that sets a dz profile that is used everywhere.

The typical use of 3D HYCOM1 fields is to have different TARGET_DENSITIES in semi-enclosed seas for layers that are always below its sill depth. For example, in the OM4 75-layer setup layers 71 and 72 are only active in the Arctic and layers 74 and 75 are only active in the Mediterranean. So the number of layers can be reduced to 71 by specifying different deep targets in these semi-enclosed seas. In this case ALE_RESOLUTION would be the same everywhere, but the resulting 71 layer configuration can be further improved by using shallow ALE_RESOLUTION in the northern hemisphere and the standard, deep, dz's in the southern hemisphere. This is safe, because deep layers are never in fixed coordinates near the equator.

To simplify this typical use case, ALE_COORDINATE_CONFIG=HYBRID_MAP requires three netCDF variables (e.g. map,sigma2,dz) with the last two being 2-D z-index fields containing a small number of profiles and the first a 2-D x-y field of index values indicating which profile to use at each location. Like HYBRID and HYBRID_3D, the 3rd variable (e.g. dz) can be replaced by a FNC1 string that sets a dz profile that is used everywhere.

The MOM_override and netcdf file that converts the standard ice_ocean_SIS2/OM4_025 example from 75 to 71 layers are in GLBm0.25_map14.tar.gz.

The 2-d REAL map array in HYBRID_MAP usually contains integer values each referencing one profile. It can instead contain non-integer values of the form I+frac, which indicate a weighted sum of profiles: (1-frac) p(I) + (frac) p(I+1). The same profile can be used multiple times, e.g. if 1st profile is also 4th can get profiles between 1 and 2 and between 1 and 3.

HYBRID_3D is more general, but HYBRID_MAP covers most practical uses.

In addition, SHALLOW_ALE_RESOLUTION implements a HYBGEN-style Z-sigma-Z near surface fixed coordinate for HYCOM1 using 3D HYBRID profiles internally. For example the US Navy's GOFS 3.1 HYCOM setup has 41 layers, with the top 14 layers in a Z-sigma-Z configuration. For MOM6 HYCOM1 this is:

SHALLOW_ALE_RESOLUTION = 14*1.0,27*0.0

for 14 1m "shallow" layers.

Let N_SIGMA be the number of consecutive non-zero entries, typically < NK. When rest depth is shallower than SUM(SHALLOW_ALE_RESOLUTION(1:N_SIGMA)) use SHALLOW_ALE_RESOLUTION. When rest depth is deeper than SUM(ALE_RESOLUTION(1:N_SIGMA)) use ALE_RESOLUTION. Otherwise use a linear sum of the two weighted by rest depth.

The default of all zeros turns this option off, and when off answers are unchanged. The new parameter SHALLOW_ALE_RESOLUTION is only present when using HYCOM1.

Answers are not changed unless SHALLOW_ALE_RESOLUTION is non-zero or ALE_COORDINATE_CONFIG is set to HYBRID_3D or HYBRID_MAP.

For more information, see Wallcraft_HYCOM1_3D_map14_v2.pdf.

[Hallberg-NOAA]

This PR contributes a valuable new capability to MOM6 with an excellent description and outstanding error handling. Apart from one very minor quibble about the white space in front of continuation lines being inconsistent with the MOM6 code style guide, I think that this PR is ready to go.

[Hallberg-NOAA]

This PR contributes a valuable new capability to MOM6 with an excellent description and outstanding error handling. Thank you for this contribution, @awallcraft .

[Hallberg-NOAA]

This PR has passed pipeline testing at https://gitlab.gfdl.noaa.gov/ogrp/mom6ci/MOM6/-/pipelines/28730 with the expected warnings about new runtime options.