[0.25deg config] MINIMUM_DEPTH & MASKING_DEPTH in MOM_grid_init

[minghangli-uni]

MINIMUM_DEPTH is a need-to-change parameter that was discussed in namelist discussion.

MINIMUM_DEPTH - changes land mask - set to zero so we control minimum depth via topog.nc

However instead of setting it to zero, it is prefered to to adjust another parameter, MASKING_DEPTH to zero, and set MINIMUM_DEPTH to the minimum value defined by topog.nc, here is 11.8m.

When only MINIMUM_DEPTH is set and MASKING_DEPTH remains at its default value (-9999), the depth is calculated as ,

  if (mask_depth == -9999.*US%m_to_Z) then
    if (min_depth<0.) then
      call MOM_error(FATAL, trim(mdl)//": MINIMUM_DEPTH<0 does not work as expected "//&
                 "unless MASKING_DEPTH has been set appropriately. Set a meaningful "//&
                 "MASKING_DEPTH to enabled negative depths (land elevations) and to "//&
                 "enable flooding.")
    endif
    ! This is the old path way. The 0.5*min_depth is obscure and is retained to be
    ! backward reproducible. If you are looking at the following line you should probably
    ! set MASKING_DEPTH. This path way does not work for negative depths, i.e. flooding.
    do j=G%jsd,G%jed ; do i=G%isd,G%ied
      D(i,j) = min( max( D(i,j), 0.5*min_depth ), max_depth )
    enddo ; enddo

The above calculation using 0.5*min_depth is considered obscure according to inline comments. On the other hand, setting MASKING_DEPTH is encouraged.

  else
    ! This is the preferred path way.
    ! mask_depth has a meaningful value; anything shallower than mask_depth is land.
    ! If min_depth<mask_depth (which happens when using positive depths and not changing
    ! MINIMUM_DEPTH) then the shallower is used to modify and determine values on land points.
    do j=G%jsd,G%jed ; do i=G%isd,G%ied
      if (D(i,j) > min(min_depth,mask_depth)) then
        D(i,j) = min( max( D(i,j), min_depth ), max_depth )
      else
        ! This statement is required for cases with masked-out PEs over the land,
        ! to remove the large initialized values (-9e30) from the halos.
        D(i,j) = min(min_depth,mask_depth)
      endif
    enddo ; enddo
  endif

MINIMUM_DEPTH is strictly to be larger than zero, while MASKING_DEPTH can be negative to enable negative depths and to enable for example flooding. Setting MASKING_DEPTH is more robust and will be adjusted as follows:

MINIMUM_DEPTH = 11.8            !   [m] default = 0.0
                                ! If MASKING_DEPTH is unspecified, then anything shallower than MINIMUM_DEPTH is
                                ! assumed to be land and all fluxes are masked out. If MASKING_DEPTH is
                                ! specified, then all depths shallower than MINIMUM_DEPTH but deeper than
                                ! MASKING_DEPTH are rounded to MINIMUM_DEPTH.
MASKING_DEPTH = 0.0             !   [m] default = -9999.0
                                ! The depth below which to mask points as land points, for which all fluxes are
                                ! zeroed out. MASKING_DEPTH is ignored if it has the special default value.

[aekiss]

Thanks for the detailed description @minghangli-uni.

To be pedantic, the min depth in the OM2 0.25° 50-level grid is actually 11.805749893188477 m - will that matter?

If this needs to match exactly, it seems like we should have an automatic way to set MINIMUM_DEPTH, so we don't need to remember to update it whenever we change the topography or number of depth levels.

[minghangli-uni]

Thank you for pointing this out @aekiss.

As long as MIN_DEPTH is between the MASKING_DEPTH=0.0 and the minimum depth (i.e., 11.805749893188477 m), the exact value of MIN_DEPTH is not critical.

[aekiss]

Yes, I was just about to post that :-)

So when we change to 75 levels we'll need to adjust MIN_DEPTH to suit the minimum we set in the updated topography.

[aekiss]

Actually, it would be simpler to set

MINIMUM_DEPTH = 0.0            !   [m] default = 0.0
                                ! If MASKING_DEPTH is unspecified, then anything shallower than MINIMUM_DEPTH is
                                ! assumed to be land and all fluxes are masked out. If MASKING_DEPTH is
                                ! specified, then all depths shallower than MINIMUM_DEPTH but deeper than
                                ! MASKING_DEPTH are rounded to MINIMUM_DEPTH.
MASKING_DEPTH = 0.0             !   [m] default = -9999.0
                                ! The depth below which to mask points as land points, for which all fluxes are
                                ! zeroed out. MASKING_DEPTH is ignored if it has the special default value.

and set the minimum depth when we generate topog.nc with topogtools min_max_depth, right?
I think that's what we meant in the namelist discussion.

[minghangli-uni]

Yes, I agree. Setting MINIMUM_DEPTH to 0.0 is simpler.

Bur it appears that if MASKING_DEPTH has its default value of -9999, it is automatically set to the same value as MINIMUM_DEPTH.

  if (mask_depth == -9999.*US%m_to_Z) mask_depth = min_depth

Since the default value of MINIMUM_DEPTH is 0, there is no need to configure these two parameters in the MOM_input.

[aekiss]

That would be even simpler, so I'm tempted to omit both parameters from MOM_input. Does that sound ok? MASKING_DEPTH = -9999 is the default, even though the comments say it's not the preferred approach.

[minghangli-uni]

Sounds good. I'll update the PR and include a note about the modifications.

[minghangli-uni]

ACCESS-NRI/access-om3-configs#78 is merged.