*+Add ePBL bottom boundary layer mixing option

[Hallberg-NOAA]

This series of five commits adds the option to do energetically consistent bottom boundary layer mixing with the new routine ePBL_BBL_column(). ePBL_BBL_column() is closely based on the surface-focused ePBL mixing in ePBL_column(), but without adding convective instability driven mixing or mean-TKE driven mixing to avoid possible double-counting. This new option is enabled by setting the new runtime parameter EPBL_BBL_EFFIC to be positive. The changes include the addition of a new mandatory vertvisc_type argument to the publicly visible routine energetic_PBL(). If both EPBL_BBL_EFFIC and BBL_EFFIC are set to positive values, there is a risk of double-counting, but this case is not being trapped for now. The changes that actually adds ePBL_BBL_column() is in the fifth of the commits in this PR.

The first commit in this series corrects a bug that causes ePBL column to set the wrong variable and then use an uninitialized variable when EPBL_ORIGINAL_PE_CALC is set to false. This bug was present when the EPBL_ORIGINAL_PE_CALC was first added on Sept. 30, 2016, but it was not detected because only the default case with EPBL_ORIGINAL_PE_CALC = True appears to being used or tested. Any runs that used this code with debugging compile options would have trapped it immediately. This will change answers when EPBL_ORIGINAL_PE_CALC is false.

The second commit corrects an unlikely bug when iterating to determine the mixed layer depth, that arises when the change between iterations exactly matches the tolerance. This bug is fixed by setting the new runtime parameter EPBL_MLD_ITER_BUG = False.

The third commit adds the ability to passively run ePBL_column() twice in a diagnostic mode and then provide diagnostics of the differences in the diffusivities and boundary layer depths that are generated with the two options. This is controlled by the new runtime parameter EPBL_OPTIONS_DIFF, which is an integer that specifies which options to change or 0 (the default) to
disable this capability. Associated with this are the new diagnostics ePBL_opt_diff_Kd_ePBL, ePBL_opt_maxdiff_Kd_ePBL and ePBL_opt_diff_h_ML, which only are registered when the differencing is enabled.

There was also some refactoring for code clarity and clean-up of some typos as a part of this third commit. Within ePBL_column(), the hp_a variable was converted from a scalar into a 1-d array to emphasize where these variables are
located and to bring ePBL_column() closer to what would be required if the new diffusivities were being applied on top of diffusivities from other processes, as is the case in ePBL_BBL_column(). As a part of these changes, there were some other reforms to the way that MOM_energetic_PBL() handles diagnostics, with the 2-d and 3-d arrays changed from allocatable arrays with enduring memory commitments in the energetic_PBL_CS type into simple arrays in energetic_PBL(),
relying on the fact that compilers will be smart enough to avoid actually allocating this memory when it is unused to avoid expanding the overall memory requirements of MOM6. A number of allocate and deallocate calls were eliminated
by these changes. In addition, explicit 'units=' descriptors were added to numerous register_diag_field() calls to help identify inconsistent conversion factors. Also, the diagnostic of the number of boundary layer depth iterations
was added to the ePBL_column_diags, which enabled the intent of the CS and G arguments to ePBL_column() to be changed to intent(in). The unnecessary extra logic associated with the use of the OBL_converged variable in ePBL_column() was eliminated, but the results are unaltered. Because the MOM_parameter_doc files were changing anyway, and because this commit is only a diagnostic change, about 6 spelling errors were corrected in ePBL parameter descriptions as a part of
this commit.

The fourth commit adds the new internal subroutine find_Kd_from_PE_chg() inside of the MOM_energetic_PBL module to directly calculate an increment in the diapycnal diffusivity from an energy input. This can be used when ePBL does not convert
released mean kinetic energy into turbulent kinetic energy (i.e., if MKE_TO_TKE_EFFIC = 0.) and is more efficient than the more general iterative approach. To preserve old answers, this new option is only enabled for the surface boundary layer when the new runtime parameter DIRECT_EPBL_MIXING_CALC is set to true. This new option can be tested passively by setting
EPBL_OPTIONS_DIFF = 3 in a run that uses ePBL. ePBL_BBL_column() also has the option to use find_Kd_from_PE_chg(), and to verify its correctness for the bottom boundary layer by setting EPBL_OPTIONS_DIFF = 4.

This PR makes several new diagnostics available that are related to bottom boundary layer mixing or the sensitivity of ePBL mixing to several parameter changes. The MOM_parameter_doc files are altered by the addition of 5 new runtime parameters, and by the correction of several spelling errors in the descriptions of other ePBL parameters. By default, all answers are bitwise
identical.

This commits in this PR include:

• f89e7db2e +(*)Add ePBL bottom boundary mixing option
• 1f688b4aa +Add and test find_Kd_from_PE_chg
• 3a6bfdea1 +Add run-time ability to debug ePBL sensitivities
• c58a4e776 +Add EPBL_MLD_ITER_BUG runtime parameter
• 6697b2dc5 *Fix a bug when EPBL_ORIGINAL_PE_CALC is false

[Hallberg-NOAA]

I am converting this to a draft PR , because while I believe that it is correct (and worth assessing), I think that it could be made much more efficient. We are not using released mean kinetic energy to drive added bottom boundary layer mixing, which means that we can solve directly for the diffusivity that can be supported by a given energy increment without having to do so iteratively with Newton's method.

[Hallberg-NOAA]

This PR has now been revised into its complete form, and ready for review. Please do not squash this PR, as each of the 5 commits that comprise this PR are significant, either in their scope or by fixing a bug.

[adcroft]

Looks good to me. Wondering is @breichl should also look at this?