+Document or eliminate undocumented interfaces

  Address undocumented interfaces by adding explicit interfaces to replaces one
level of the pass-throughs or eliminated them.  Specifically

  - Eliminated global_field_sum() from MOM_domains, as it is no longer used
    anywhere in the MOM6 code or drivers.  At the config_src/infra level, the
    pass-through calls to mpp_global_sum are commented out in case there are
    other versions of the MOM6 code that still use global_field_sum.

  - Added explicit interfaces to horizontal_interp_init() and
    time_interp_extern_init() in the config_src/infra rather that leaving them
    as undocumented pass-throughs to the FMS code.

  - Added the explicit subroutine stdout_if_root() to MOM_io.F90 to replace an undocumented
    pass-through to the FMS stdout function.

  - Added comments describing the publicly visible encoding parameters ind_flux,
    ind_alpha, and ind_csurf that are a part of the coupler_types module.

  - Removed the unnecessary or commented-out public declarations for
    post_data_1d_k, vert_fill_TS, and legacy_diabatic.

All answers are bitwise identical, but there are some minor changes to the
names of subroutines offered at the config_src/infra level to permit the
documentation of these interfaces without running afoul of some bugs with
certain versions of the gnu compiler.

config_src/drivers/mct_cap/mom_surface_forcing_mct.F90

@@ -9,7 +9,6 @@ module MOM_surface_forcing_mct
 use MOM_diag_mediator,    only : diag_ctrl
 use MOM_diag_mediator,    only : safe_alloc_ptr, time_type
 use MOM_domains,          only : pass_vector, pass_var, fill_symmetric_edges
-use MOM_domains,          only : global_field_sum, BITWISE_EXACT_SUM
 use MOM_domains,          only : AGRID, BGRID_NE, CGRID_NE, To_All
 use MOM_domains,          only : To_North, To_East, Omit_Corners
 use MOM_error_handler,    only : MOM_error, WARNING, FATAL, is_root_pe, MOM_mesg

config_src/drivers/nuopc_cap/mom_surface_forcing_nuopc.F90

@@ -10,7 +10,6 @@ module MOM_surface_forcing_nuopc
 use MOM_diag_mediator,    only : diag_ctrl
 use MOM_diag_mediator,    only : safe_alloc_ptr, time_type
 use MOM_domains,          only : pass_vector, pass_var, fill_symmetric_edges
-use MOM_domains,          only : global_field_sum, BITWISE_EXACT_SUM
 use MOM_domains,          only : AGRID, BGRID_NE, CGRID_NE, To_All
 use MOM_domains,          only : To_North, To_East, Omit_Corners
 use MOM_error_handler,    only : MOM_error, WARNING, FATAL, is_root_pe, MOM_mesg

config_src/infra/FMS1/MOM_domain_infra.F90

@@ -27,7 +27,7 @@ module MOM_domain_infra
 use fms_affinity_mod, only : fms_affinity_init, fms_affinity_set, fms_affinity_get
 
 ! This subroutine is not in MOM6/src but may be required by legacy drivers
-use mpp_domains_mod, only : global_field_sum => mpp_global_sum
+! use mpp_domains_mod, only : global_field_sum => mpp_global_sum
 
 ! The `group_pass_type` fields are never accessed, so we keep it as an FMS type
 use mpp_domains_mod, only : group_pass_type => mpp_group_update_type
@@ -45,13 +45,13 @@ module MOM_domain_infra
 public :: redistribute_array, broadcast_domain, same_domain, global_field
 public :: get_simple_array_i_ind, get_simple_array_j_ind
 public :: MOM_thread_affinity_set, set_MOM_thread_affinity
-! These are encoding constant parmeters.
+! These are encoding constant parmeters with self-explanatory names.
 public :: To_East, To_West, To_North, To_South, To_All, Omit_Corners
 public :: AGRID, BGRID_NE, CGRID_NE, SCALAR_PAIR
 public :: CORNER, CENTER, NORTH_FACE, EAST_FACE
 ! These are no longer used by MOM6 because the reproducing sum works so well, but they are
 ! still referenced by some of the non-GFDL couplers.
-public :: global_field_sum, BITWISE_EXACT_SUM
+! public :: global_field_sum, BITWISE_EXACT_SUM
 
 !> Do a halo update on an array
 interface pass_var

config_src/infra/FMS1/MOM_interp_infra.F90

@@ -14,8 +14,8 @@ module MOM_interp_infra
 
 implicit none ; private
 
-public :: horiz_interp_type, horiz_interp_init
-public :: time_interp_extern, init_extern_field, time_interp_external_init
+public :: horiz_interp_type, horizontal_interp_init
+public :: time_interp_extern, init_extern_field, time_interp_extern_init
 public :: get_external_field_info, axistype, get_axis_data
 public :: run_horiz_interp, build_horiz_interp_weights
 
@@ -39,6 +39,16 @@ module MOM_interp_infra
 
 contains
 
+!> Do any initialization for the horizontal interpolation
+subroutine horizontal_interp_init()
+  call horiz_interp_init()
+end subroutine horizontal_interp_init
+
+!> Do any initialization for the time and space interpolation infrastructure
+subroutine time_interp_extern_init()
+  call time_interp_external_init()
+end subroutine time_interp_extern_init
+
 !> perform horizontal interpolation of a 2d field using pre-computed weights
 !! source and destination coordinates are 2d
 subroutine horiz_interp_from_weights_field2d(Interp, data_in, data_out, verbose, mask_in, mask_out, &

config_src/infra/FMS2/MOM_domain_infra.F90

@@ -27,7 +27,7 @@ module MOM_domain_infra
 use fms_affinity_mod, only : fms_affinity_init, fms_affinity_set, fms_affinity_get
 
 ! This subroutine is not in MOM6/src but may be required by legacy drivers
-use mpp_domains_mod, only : global_field_sum => mpp_global_sum
+! use mpp_domains_mod, only : global_field_sum => mpp_global_sum
 
 ! The `group_pass_type` fields are never accessed, so we keep it as an FMS type
 use mpp_domains_mod, only : group_pass_type => mpp_group_update_type
@@ -45,13 +45,13 @@ module MOM_domain_infra
 public :: redistribute_array, broadcast_domain, same_domain, global_field
 public :: get_simple_array_i_ind, get_simple_array_j_ind
 public :: MOM_thread_affinity_set, set_MOM_thread_affinity
-! These are encoding constant parmeters.
+! These are encoding constant parmeters with self-explanatory names.
 public :: To_East, To_West, To_North, To_South, To_All, Omit_Corners
 public :: AGRID, BGRID_NE, CGRID_NE, SCALAR_PAIR
 public :: CORNER, CENTER, NORTH_FACE, EAST_FACE
 ! These are no longer used by MOM6 because the reproducing sum works so well, but they are
 ! still referenced by some of the non-GFDL couplers.
-public :: global_field_sum, BITWISE_EXACT_SUM
+! public :: global_field_sum, BITWISE_EXACT_SUM
 
 !> Do a halo update on an array
 interface pass_var

config_src/infra/FMS2/MOM_interp_infra.F90

@@ -14,8 +14,8 @@ module MOM_interp_infra
 
 implicit none ; private
 
-public :: horiz_interp_type, horiz_interp_init
-public :: time_interp_extern, init_extern_field, time_interp_external_init
+public :: horiz_interp_type, horizontal_interp_init
+public :: time_interp_extern, init_extern_field, time_interp_extern_init
 public :: get_external_field_info, axistype, get_axis_data
 public :: run_horiz_interp, build_horiz_interp_weights
 
@@ -39,6 +39,16 @@ module MOM_interp_infra
 
 contains
 
+!> Do any initialization for the horizontal interpolation
+subroutine horizontal_interp_init()
+  call horiz_interp_init()
+end subroutine horizontal_interp_init
+
+!> Do any initialization for the time and space interpolation infrastructure
+subroutine time_interp_extern_init()
+  call time_interp_external_init()
+end subroutine time_interp_extern_init
+
 !> perform horizontal interpolation of a 2d field using pre-computed weights
 !! source and destination coordinates are 2d
 subroutine horiz_interp_from_weights_field2d(Interp, data_in, data_out, verbose, mask_in, mask_out, &
@@ -61,7 +71,6 @@ subroutine horiz_interp_from_weights_field2d(Interp, data_in, data_out, verbose,
 
 end subroutine horiz_interp_from_weights_field2d
 
-
 !> perform horizontal interpolation of a 3d field using pre-computed weights
 !! source and destination coordinates are 2d
 subroutine horiz_interp_from_weights_field3d(Interp, data_in, data_out, verbose, mask_in, mask_out, &

src/framework/MOM_coupler_types.F90

@@ -19,8 +19,10 @@ module MOM_coupler_types
 public :: set_coupler_type_data, extract_coupler_type_data, coupler_type_redistribute_data
 public :: coupler_type_copy_data, coupler_type_increment_data, coupler_type_rescale_data
 public :: atmos_ocn_coupler_flux, coupler_type_data_override
-public :: ind_flux, ind_alpha, ind_csurf
 public :: coupler_1d_bc_type, coupler_2d_bc_type, coupler_3d_bc_type
+! These are encoding constant parameters that indicate whether a flux, solubility or
+! surface ocean concentration are being set or accessed with an inquiry.
+public :: ind_flux, ind_alpha, ind_csurf
 
 !> This is the interface to spawn one coupler_bc_type into another.
 interface coupler_type_spawn

src/framework/MOM_diag_mediator.F90

@@ -41,7 +41,6 @@ module MOM_diag_mediator
 public set_axes_info, post_data, register_diag_field, time_type
 public post_product_u, post_product_sum_u, post_product_v, post_product_sum_v
 public set_masks_for_axes
-public post_data_1d_k
 public safe_alloc_ptr, safe_alloc_alloc
 public enable_averaging, enable_averages, disable_averaging, query_averaging_enabled
 public diag_mediator_init, diag_mediator_end, set_diag_mediator_grid

src/framework/MOM_domains.F90

@@ -10,14 +10,14 @@ module MOM_domains
 use MOM_domain_infra,     only : create_MOM_domain, clone_MOM_domain, deallocate_MOM_domain
 use MOM_domain_infra,     only : get_domain_extent, get_domain_components, same_domain
 use MOM_domain_infra,     only : compute_block_extent, get_global_shape
-use MOM_domain_infra,     only : pass_var, pass_vector, fill_symmetric_edges, global_field_sum
+use MOM_domain_infra,     only : pass_var, pass_vector, fill_symmetric_edges
 use MOM_domain_infra,     only : pass_var_start, pass_var_complete
 use MOM_domain_infra,     only : pass_vector_start, pass_vector_complete
 use MOM_domain_infra,     only : create_group_pass, do_group_pass
 use MOM_domain_infra,     only : start_group_pass, complete_group_pass
 use MOM_domain_infra,     only : rescale_comp_data, global_field, redistribute_array, broadcast_domain
 use MOM_domain_infra,     only : MOM_thread_affinity_set, set_MOM_thread_affinity
-use MOM_domain_infra,     only : AGRID, BGRID_NE, CGRID_NE, SCALAR_PAIR, BITWISE_EXACT_SUM
+use MOM_domain_infra,     only : AGRID, BGRID_NE, CGRID_NE, SCALAR_PAIR
 use MOM_domain_infra,     only : CORNER, CENTER, NORTH_FACE, EAST_FACE
 use MOM_domain_infra,     only : To_East, To_West, To_North, To_South, To_All, Omit_Corners
 use MOM_error_handler,    only : MOM_error, MOM_mesg, NOTE, WARNING, FATAL
@@ -54,9 +54,6 @@ module MOM_domains
 public :: CORNER, CENTER, NORTH_FACE, EAST_FACE
 !> These encoding constants indicate communication patterns.  In practice they can be added.
 public :: To_East, To_West, To_North, To_South, To_All, Omit_Corners
-! These are no longer used by MOM6 because the reproducing sum works so well, but they are
-! still referenced by some of the non-GFDL couplers.
-public :: global_field_sum, BITWISE_EXACT_SUM
 
 contains
 

src/framework/MOM_horizontal_regridding.F90

@@ -12,8 +12,9 @@ module MOM_horizontal_regridding
 use MOM_error_handler, only : MOM_get_verbosity
 use MOM_file_parser,   only : get_param, log_param, log_version, param_file_type
 use MOM_grid,          only : ocean_grid_type
-use MOM_interpolate,   only : time_interp_external, horiz_interp_init
-use MOM_interpolate,   only : build_horiz_interp_weights, run_horiz_interp, horiz_interp_type
+use MOM_interpolate,   only : time_interp_external
+use MOM_interp_infra,  only : run_horiz_interp, build_horiz_interp_weights
+use MOM_interp_infra,  only : horiz_interp_type, horizontal_interp_init
 use MOM_interp_infra,  only : axistype, get_external_field_info, get_axis_data
 use MOM_time_manager,  only : time_type
 use MOM_io,            only : axis_info, get_axis_info, get_var_axes_info, MOM_read_data
@@ -410,7 +411,7 @@ subroutine horiz_interp_and_extrap_tracer_record(filename, varnam,  conversion,
     allocate(tr_in(is:ie,js:je), source=0.0)
     allocate(mask_in(is:ie,js:je), source=0.0)
   else
-    call horiz_interp_init()
+    call horizontal_interp_init()
     lon_in = lon_in*PI_180
     lat_in = lat_in*PI_180
     allocate(x_in(id,jdp), y_in(id,jdp))
@@ -708,7 +709,7 @@ subroutine horiz_interp_and_extrap_tracer_fms_id(fms_id,  Time, conversion, G, t
     else
       jdp = jd
     endif
-    call horiz_interp_init()
+    call horizontal_interp_init()
     lon_in = lon_in*PI_180
     lat_in = lat_in*PI_180
     allocate(x_in(id,jdp), y_in(id,jdp))

src/framework/MOM_interpolate.F90

@@ -6,15 +6,15 @@ module MOM_interpolate
 use MOM_array_transform, only : allocate_rotated_array, rotate_array
 use MOM_error_handler,   only : MOM_error, FATAL
 use MOM_interp_infra,    only : time_interp_extern, init_external_field=>init_extern_field
-use MOM_interp_infra,    only : time_interp_external_init, get_external_field_info
-use MOM_interp_infra,    only : horiz_interp_type, horiz_interp_init
+use MOM_interp_infra,    only : time_interp_external_init=>time_interp_extern_init
+use MOM_interp_infra,    only : horiz_interp_type, get_external_field_info
 use MOM_interp_infra,    only : run_horiz_interp, build_horiz_interp_weights
 use MOM_time_manager,    only : time_type
 
 implicit none ; private
 
 public :: time_interp_external, init_external_field, time_interp_external_init, get_external_field_info
-public :: horiz_interp_type, horiz_interp_init, run_horiz_interp, build_horiz_interp_weights
+public :: horiz_interp_type, run_horiz_interp, build_horiz_interp_weights
 
 !> Read a field based on model time, and rotate to the model domain.
 interface time_interp_external

src/framework/MOM_io.F90

@@ -21,7 +21,6 @@ module MOM_io
 use MOM_io_infra,         only : get_file_times, axistype, get_axis_data, get_filename_suffix
 use MOM_io_infra,         only : write_field, write_metadata, write_version
 use MOM_io_infra,         only : MOM_namelist_file, check_namelist_error, io_infra_init, io_infra_end
-use MOM_io_infra,         only : stdout_if_root
 use MOM_io_infra,         only : APPEND_FILE, ASCII_FILE, MULTIPLE, NETCDF_FILE, OVERWRITE_FILE
 use MOM_io_infra,         only : READONLY_FILE, SINGLE_FILE, WRITEONLY_FILE
 use MOM_io_infra,         only : CENTER, CORNER, NORTH_FACE, EAST_FACE
@@ -587,6 +586,11 @@ subroutine reopen_file(IO_handle, filename, vars, novars, fields, threading, tim
 
 end subroutine reopen_file
 
+!> Return the index of sdtout if called from the root PE, or 0 for other PEs.
+integer function stdout_if_root()
+  stdout_if_root = 0
+  if (is_root_PE()) stdout_if_root = stdout
+end function stdout_if_root
 
 !> This function determines how many time levels a variable has in a file.
 function num_timelevels(filename, varname, min_dims) result(n_time)

src/parameterizations/lateral/MOM_thickness_diffuse.F90

@@ -25,7 +25,6 @@ module MOM_thickness_diffuse
 #include <MOM_memory.h>
 
 public thickness_diffuse, thickness_diffuse_init, thickness_diffuse_end
-! public vert_fill_TS
 public thickness_diffuse_get_KH
 
 ! A note on unit descriptions in comments: MOM6 uses units that can be rescaled for dimensional

src/parameterizations/vertical/MOM_diabatic_driver.F90

@@ -81,7 +81,6 @@ module MOM_diabatic_driver
 public extract_diabatic_member
 public adiabatic
 public adiabatic_driver_init
-! public legacy_diabatic
 
 ! A note on unit descriptions in comments: MOM6 uses units that can be rescaled for dimensional
 ! consistency testing. These are noted in comments with units like Z, H, L, and T, along with