+*Change defaults for 3 parameters to better values (#1509)

NOTE: Initial submission included 4 parameters.
`PARALLEL_RESTARTFILES` was dropped after an issue was detected.

Full commit log history below.

* +*Change defaults for 4 parameters to better values

  Updated the defaults of 4 run-time parameters (INTERNAL_WAVE_SPEED_BETTER_EST,
PARALLEL_RESTARTFILES, EPBL_MLD_BISECTION, and BBL_USE_EOS) to more appropriate
values.  In each case, the previous default was simply the older setting, and
not the better recommendation.  It also adds logic determining whether
SIMPLE_TKE_TO_KD does anything, and only log its setting if it does.  These
default changes were discussed by the MOM6 consortium as a whole in June, 2021
and were widely agreed to. In addition this commit removes the old obsoleted
runtime parameter ORIG_MLD_ITERATION, and obsoletes the runtime parameter
LARGE_FILE_SUPPORT, and it adds comments describing several real variables and
their units.  Because this changes several default values, it will change
answers unless these parameters are explicitly set in the MOM_input files.
However, because MOM6-examples PR #344 does set these values to their old
defaults where they are used, no answers are changed in the MOM6-examples
regression suite, although there are changes to the MOM_parameter_doc files.

* +Reverted default for PARALLEL_RESTARTFILES

  Reverted the default for PARALLEL_RESTARTFILES to False because the TC restart
testing was having problems with this set to True.  This is surprising because
PARALLEL_RESTARTFILES = True has been used in production runs for many years now
without any indication that MOM6 fails to reproduce across restarts in this
mode, so this could be an issue with the TC testing.  In the mean time,
reverting this default will allow the other changes to be accepted while this
curious behavior is explored separately.  Several comments related to
PARALLEL_RESTARTFILES were also updated for consistency. All answers are bitwise
identical.

src/diagnostics/MOM_diagnostics.F90

@@ -1644,7 +1644,7 @@ subroutine MOM_diagnostics_init(MIS, ADp, CDp, Time, G, GV, US, param_file, diag
                  units="m s-1", default=0.0, scale=US%m_s_to_L_T)
   call get_param(param_file, mdl, "INTERNAL_WAVE_SPEED_BETTER_EST", better_speed_est, &
                  "If true, use a more robust estimate of the first mode wave speed as the "//&
-                 "starting point for iterations.", default=.false.) !### Change the default.
+                 "starting point for iterations.", default=.true.)
   call get_param(param_file, mdl, "DEFAULT_2018_ANSWERS", default_2018_answers, &
                  "This sets the default value for the various _2018_ANSWERS parameters.", &
                  default=.false.)

src/diagnostics/MOM_obsolete_params.F90

@@ -68,7 +68,6 @@ subroutine find_obsolete_params(param_file)
                      hint="Use NUM_DIAG_COORDS, DIAG_COORDS and DIAG_COORD_DEF_Z")
 
   call obsolete_real(param_file, "VSTAR_SCALE_FACTOR", hint="Use EPBL_VEL_SCALE_FACTOR instead.")
-  call obsolete_logical(param_file, "ORIG_MLD_ITERATION", .false.)
 
   call obsolete_real(param_file, "VSTAR_SCALE_COEF")
   call obsolete_real(param_file, "ZSTAR_RIGID_SURFACE_THRESHOLD")
@@ -88,6 +87,7 @@ subroutine find_obsolete_params(param_file)
   call obsolete_logical(param_file, "MSTAR_FIXED", hint="Instead use MSTAR_MODE.")
   call obsolete_logical(param_file, "USE_VISBECK_SLOPE_BUG", .false.)
 
+  call obsolete_logical(param_file, "LARGE_FILE_SUPPORT", .true.)
   call obsolete_real(param_file, "MIN_Z_DIAG_INTERVAL")
   call obsolete_char(param_file, "Z_OUTPUT_GRID_FILE")
 

src/framework/MOM_restart.F90

@@ -73,10 +73,10 @@ module MOM_restart
                         !! file.  Otherwise some fields must be initialized approximately.
   integer :: novars = 0 !< The number of restart fields that have been registered.
   integer :: num_obsolete_vars = 0  !< The number of obsolete restart fields that have been registered.
-  logical :: parallel_restartfiles  !< If true, each PE writes its own restart file,
-                                    !! otherwise they are combined internally.
-  logical :: large_file_support     !< If true, NetCDF 3.6 or later is being used
-                                    !! and large-file-support is enabled.
+  logical :: parallel_restartfiles  !< If true, the IO layout is used to group processors that write
+                                    !! to the same restart file or each processor writes its own
+                                    !! (numbered) restart file.  If false, a single restart file is
+                                    !! generated after internally combining output from all PEs.
   logical :: new_run                !< If true, the input filenames and restart file existence will
                                     !! result in a new run that is not initialized from restart files.
   logical :: new_run_set = .false.  !< If true, new_run has been determined for this restart_CS.
@@ -885,9 +885,10 @@ subroutine save_restart(directory, time, G, CS, time_stamped, filename, GV, num_
                                         ! to the name of files after the first.
   integer(kind=8) :: var_sz, size_in_file ! The size in bytes of each variable
                                         ! and the variables already in a file.
-  integer(kind=8) :: max_file_size = 2147483647_8 ! The maximum size in bytes
-                                        ! for any one file.  With NetCDF3,
-                                        ! this should be 2 Gb or less.
+  integer(kind=8), parameter :: max_file_size = 4294967292_8 ! The maximum size in bytes for the
+                                        ! starting position of each variable in a file's record,
+                                        ! based on the use of NetCDF 3.6 or later.  For earlier
+                                        ! versions of NetCDF, the value was 2147483647_8.
   integer :: start_var, next_var        ! The starting variables of the
                                         ! current and next files.
   type(file_type) :: IO_handle          ! The I/O handle of the open fileset
@@ -910,10 +911,6 @@ subroutine save_restart(directory, time, G, CS, time_stamped, filename, GV, num_
   if (CS%novars > CS%max_fields) call restart_error(CS)
 
   ! With parallel read & write, it is possible to disable the following...
-
-  ! The maximum file size is 4294967292, according to the NetCDF documentation.
-  if (CS%large_file_support) max_file_size = 4294967292_8
-
   num_files = 0
   next_var = 0
   nz = 1 ; if (present(GV)) nz = GV%ke
@@ -1541,13 +1538,11 @@ subroutine restart_init(param_file, CS, restart_root)
   ! Determine whether all paramters are set to their default values.
   call get_param(param_file, mdl, "PARALLEL_RESTARTFILES", CS%parallel_restartfiles, &
                  default=.false., do_not_log=.true.)
-  call get_param(param_file, mdl, "LARGE_FILE_SUPPORT", CS%large_file_support, &
-                 default=.true., do_not_log=.true.)
   call get_param(param_file, mdl, "MAX_FIELDS", CS%max_fields, default=100, do_not_log=.true.)
   call get_param(param_file, mdl, "RESTART_CHECKSUMS_REQUIRED", CS%checksum_required, &
                  default=.true., do_not_log=.true.)
-  all_default = ((.not.CS%parallel_restartfiles) .and. (CS%large_file_support) .and. &
-                 (CS%max_fields == 100) .and. (CS%checksum_required))
+  all_default = ((.not.CS%parallel_restartfiles) .and. (CS%max_fields == 100) .and. &
+                 (CS%checksum_required))
   if (.not.present(restart_root)) then
     call get_param(param_file, mdl, "RESTARTFILE", CS%restartfile, &
                    default="MOM.res", do_not_log=.true.)
@@ -1557,8 +1552,9 @@ subroutine restart_init(param_file, CS, restart_root)
   ! Read all relevant parameters and write them to the model log.
   call log_version(param_file, mdl, version, "", all_default=all_default)
   call get_param(param_file, mdl, "PARALLEL_RESTARTFILES", CS%parallel_restartfiles, &
-                 "If true, each processor writes its own restart file, "//&
-                 "otherwise a single restart file is generated", &
+                 "If true, the IO layout is used to group processors that write to the same "//&
+                 "restart file or each processor writes its own (numbered) restart file. "//&
+                 "If false, a single restart file is generated combining output from all PEs.", &
                  default=.false.)
 
   if (present(restart_root)) then
@@ -1568,10 +1564,6 @@ subroutine restart_init(param_file, CS, restart_root)
     call get_param(param_file, mdl, "RESTARTFILE", CS%restartfile, &
                  "The name-root of the restart file.", default="MOM.res")
   endif
-  call get_param(param_file, mdl, "LARGE_FILE_SUPPORT", CS%large_file_support, &
-                 "If true, use the file-size limits with NetCDF large "//&
-                 "file support (4Gb), otherwise the limit is 2Gb.", &
-                 default=.true.)
   call get_param(param_file, mdl, "MAX_FIELDS", CS%max_fields, &
                  "The maximum number of restart fields that can be used.", &
                  default=100)

src/initialization/MOM_shared_initialization.F90

@@ -1300,8 +1300,9 @@ subroutine write_ocean_geometry_file(G, param_file, directory, geom_file, US)
   endif
 
   call get_param(param_file, mdl, "PARALLEL_RESTARTFILES", multiple_files, &
-                 "If true, each processor writes its own restart file, "//&
-                 "otherwise a single restart file is generated", &
+                 "If true, the IO layout is used to group processors that write to the same "//&
+                 "restart file or each processor writes its own (numbered) restart file. "//&
+                 "If false, a single restart file is generated combining output from all PEs.", &
                  default=.false.)
   file_threading = SINGLE_FILE
   if (multiple_files) file_threading = MULTIPLE

src/parameterizations/lateral/MOM_lateral_mixing_coeffs.F90

@@ -1535,7 +1535,7 @@ subroutine VarMix_init(Time, G, GV, US, param_file, diag, CS)
                  units="m s-1", default=0.0, scale=US%m_s_to_L_T)
     call get_param(param_file, mdl, "INTERNAL_WAVE_SPEED_BETTER_EST", better_speed_est, &
                  "If true, use a more robust estimate of the first mode wave speed as the "//&
-                 "starting point for iterations.", default=.false.) !### Change the default.
+                 "starting point for iterations.", default=.true.)
     call wave_speed_init(CS%wave_speed_CSp, use_ebt_mode=CS%Resoln_use_ebt, &
                          mono_N2_depth=N2_filter_depth, remap_answers_2018=remap_answers_2018, &
                          better_speed_est=better_speed_est, min_speed=wave_speed_min, &

src/parameterizations/vertical/MOM_energetic_PBL.F90

@@ -2181,7 +2181,7 @@ subroutine energetic_PBL_init(Time, G, GV, US, param_file, diag, CS)
                  "If true, use bisection with the iterative determination of the self-consistent "//&
                  "mixed layer depth.  Otherwise use the false position after a maximum and minimum "//&
                  "bound have been evaluated and the returned value or bisection before this.", &
-                 default=.true., do_not_log=.not.CS%Use_MLD_iteration) !### The default should become false.
+                 default=.false., do_not_log=.not.CS%Use_MLD_iteration)
   call get_param(param_file, mdl, "EPBL_MLD_MAX_ITS", CS%max_MLD_its, &
                  "The maximum number of iterations that can be used to find a self-consistent "//&
                  "mixed layer depth.  If EPBL_MLD_BISECTION is true, the maximum number "//&

src/parameterizations/vertical/MOM_set_diffusivity.F90

@@ -2007,9 +2007,14 @@ subroutine set_diffusivity_init(Time, G, GV, US, param_file, diag, CS, int_tide_
   ! This include declares and sets the variable "version".
 # include "version_variable.h"
   character(len=40)  :: mdl = "MOM_set_diffusivity"  ! This module's name.
-  real :: omega_frac_dflt
+  real    :: omega_frac_dflt ! The default value for the fraction of the absolute rotation rate
+                             ! that is used in place of the absolute value of the local Coriolis
+                             ! parameter in the denominator of some expressions [nondim]
   logical :: Bryan_Lewis_diffusivity ! If true, the background diapycnal diffusivity uses
                                      ! the Bryan-Lewis (1979) style tanh profile.
+  logical :: use_regridding  ! If true, use the ALE algorithm rather than layered
+                             ! isopycnal or stacked shallow water mode.
+  logical :: TKE_to_Kd_used  ! If true, TKE_to_Kd and maxTKE need to be calculated.
   integer :: i, j, is, ie, js, je
   integer :: isd, ied, jsd, jed
 
@@ -2151,11 +2156,15 @@ subroutine set_diffusivity_init(Time, G, GV, US, param_file, diag, CS, int_tide_
   endif
   CS%id_Kd_BBL = register_diag_field('ocean_model', 'Kd_BBL', diag%axesTi, Time, &
                  'Bottom Boundary Layer Diffusivity', 'm2 s-1', conversion=US%Z2_T_to_m2_s)
+
+  TKE_to_Kd_used = (CS%use_tidal_mixing .or. CS%ML_radiation .or. &
+                   (CS%bottomdraglaw .and. .not.CS%use_LOTW_BBL_diffusivity))
   call get_param(param_file, mdl, "SIMPLE_TKE_TO_KD", CS%simple_TKE_to_Kd, &
                  "If true, uses a simple estimate of Kd/TKE that will "//&
                  "work for arbitrary vertical coordinates. If false, "//&
                  "calculates Kd/TKE and bounds based on exact energetics "//&
-                 "for an isopycnal layer-formulation.", default=.false.)
+                 "for an isopycnal layer-formulation.", &
+                 default=.false., do_not_log=.not.TKE_to_Kd_used)
 
   ! set params related to the background mixing
   call bkgnd_mixing_init(Time, G, GV, US, param_file, CS%diag, CS%bkgnd_mixing_csp)
@@ -2176,8 +2185,15 @@ subroutine set_diffusivity_init(Time, G, GV, US, param_file, diag, CS, int_tide_
                  "The maximum permitted increment for the diapycnal "//&
                  "diffusivity from TKE-based parameterizations, or a negative "//&
                  "value for no limit.", units="m2 s-1", default=-1.0, scale=US%m2_s_to_Z2_T)
-  if (CS%simple_TKE_to_Kd .and. CS%Kd_max<=0.) call MOM_error(FATAL, &
+  if (CS%simple_TKE_to_Kd) then
+    if (CS%Kd_max<=0.) call MOM_error(FATAL, &
          "set_diffusivity_init: To use SIMPLE_TKE_TO_KD, KD_MAX must be set to >0.")
+    call get_param(param_file, mdl, "USE_REGRIDDING", use_regridding, &
+                 do_not_log=.true., default=.false.)
+    if (use_regridding) call MOM_error(WARNING, &
+         "set_diffusivity_init: SIMPLE_TKE_TO_KD can not be used reliably with USE_REGRIDDING.")
+  endif
+
   call get_param(param_file, mdl, "KD_ADD", CS%Kd_add, &
                  "A uniform diapycnal diffusivity that is added "//&
                  "everywhere without any filtering or scaling.", &

src/parameterizations/vertical/MOM_set_viscosity.F90

@@ -1916,9 +1916,15 @@ subroutine set_visc_init(Time, G, GV, US, param_file, diag, visc, CS, restart_CS
   type(ocean_OBC_type),    pointer       :: OBC  !< A pointer to an open boundary condition structure
 
   ! Local variables
-  real    :: Csmag_chan_dflt, smag_const1, TKE_decay_dflt, bulk_Ri_ML_dflt
-  real    :: Kv_background
-  real    :: omega_frac_dflt
+  real    :: Csmag_chan_dflt ! The default value for SMAG_CONST_CHANNEL [nondim]
+  real    :: smag_const1     ! The default value for the Smagorinsky Laplacian coefficient [nondim]
+  real    :: TKE_decay_dflt  ! The default value of a coeficient scaling the vertical decay
+                             ! rate of TKE [nondim]
+  real    :: bulk_Ri_ML_dflt ! The default bulk Richardson number for a bulk mixed layer [nondim]
+  real    :: Kv_background   ! The background kinematic viscosity in the interior [m2 s-1]
+  real    :: omega_frac_dflt ! The default value for the fraction of the absolute rotation rate that
+                             ! is used in place of the absolute value of the local Coriolis
+                             ! parameter in the denominator of some expressions [nondim]
   real    :: Z_rescale     ! A rescaling factor for heights from the representation in
                            ! a restart file to the internal representation in this run.
   real    :: I_T_rescale   ! A rescaling factor for time from the internal representation in this run
@@ -1930,7 +1936,10 @@ subroutine set_visc_init(Time, G, GV, US, param_file, diag, visc, CS, restart_CS
   logical :: default_2018_answers
   logical :: use_kappa_shear, adiabatic, use_omega, MLE_use_PBL_MLD
   logical :: use_KPP
-  logical :: use_regridding
+  logical :: use_regridding  ! If true, use the ALE algorithm rather than layered
+                             ! isopycnal or stacked shallow water mode.
+  logical :: use_temperature ! If true, temperature and salinity are used as state variables.
+  logical :: use_EOS         ! If true, density calculated from T & S using an equation of state.
   character(len=200) :: filename, tideamp_file
   type(OBC_segment_type), pointer :: segment => NULL() ! pointer to OBC segment type
   ! This include declares and sets the variable "version".
@@ -2071,15 +2080,18 @@ subroutine set_visc_init(Time, G, GV, US, param_file, diag, visc, CS, restart_CS
                    "BOTTOMDRAGLAW is defined.", units="m s-1", default=0.0, scale=US%m_s_to_L_T)
     endif
     call get_param(param_file, mdl, "USE_REGRIDDING", use_regridding, &
-         do_not_log = .true., default = .false. )
+                 do_not_log=.true., default=.false. )
+    call get_param(param_file, mdl, "ENABLE_THERMODYNAMICS", use_temperature, &
+                 default=.true., do_not_log=.true.)
+    call get_param(param_file, mdl, "USE_EOS", use_EOS, &
+                 default=use_temperature, do_not_log=.true.)
     call get_param(param_file, mdl, "BBL_USE_EOS", CS%BBL_use_EOS, &
-                 "If true, use the equation of state in determining the "//&
-                 "properties of the bottom boundary layer.  Otherwise use "//&
-                 "the layer target potential densities.  The default of "//&
-                 "this is determined by USE_REGRIDDING.", default=use_regridding)
+                 "If true, use the equation of state in determining the properties of the "//&
+                 "bottom boundary layer.  Otherwise use the layer target potential densities.  "//&
+                 "The default of this parameter is the value of USE_EOS.", &
+                 default=use_EOS, do_not_log=.not.use_temperature)
     if (use_regridding .and. (.not. CS%BBL_use_EOS)) &
-      call MOM_error(FATAL,"When using MOM6 in ALE mode it is required to "//&
-           "set BBL_USE_EOS to True")
+      call MOM_error(FATAL,"When using MOM6 in ALE mode it is required to set BBL_USE_EOS to True.")
   endif
   call get_param(param_file, mdl, "BBL_THICK_MIN", CS%BBL_thick_min, &
                  "The minimum bottom boundary layer thickness that can be "//&