+Add 11 units arguments to get_param calls

  Add units arguments to 11 get_param calls in 8 files, and added scale=1.0
arguments to 3 get_param calls in solo_driver/MOM_driver.F90, along with
comments explaining why these time variables are not being rescaled.  Also
changed comments describing the various units that might be used for geoLat or
geoLon variables in the ocean_grid_type to use standard syntax.  The added units
arguments lead to some minor differences in MOM_parameter_doc files, but all
answers are bitwise identical.

config_src/drivers/mct_cap/mom_surface_forcing_mct.F90

@@ -1119,7 +1119,7 @@ subroutine surface_forcing_init(Time, G, US, param_file, diag, CS, restore_salt,
   call get_param(param_file, mdl, "WIND_STRESS_MULTIPLIER", CS%wind_stress_multiplier, &
                  "A factor multiplying the wind-stress given to the ocean by the "//&
                  "coupler. This is used for testing and should be =1.0 for any "//&
-                 "production runs.", default=1.0)
+                 "production runs.", units="nondim", default=1.0)
 
   if (restore_salt) then
     call get_param(param_file, mdl, "FLUXCONST", CS%Flux_const, &

config_src/drivers/nuopc_cap/mom_surface_forcing_nuopc.F90

@@ -1209,7 +1209,7 @@ subroutine surface_forcing_init(Time, G, US, param_file, diag, CS, restore_salt,
   call get_param(param_file, mdl, "WIND_STRESS_MULTIPLIER", CS%wind_stress_multiplier, &
                  "A factor multiplying the wind-stress given to the ocean by the "//&
                  "coupler. This is used for testing and should be =1.0 for any "//&
-                 "production runs.", default=1.0)
+                 "production runs.", units="nondim", default=1.0)
 
   call get_param(param_file, mdl, "USE_CFC_CAP", CS%use_CFC, &
                  default=.false., do_not_log=.true.)

config_src/drivers/solo_driver/MOM_driver.F90

@@ -331,15 +331,17 @@ program MOM6
 
   ! Read all relevant parameters and write them to the model log.
   call log_version(param_file, mod_name, version, "")
-  call get_param(param_file, mod_name, "DT", dt, fail_if_missing=.true.)
+  ! The following get_param calls setting timesteps use the argument scale=1.0 to
+  ! emphasize that this driver code works in MKS units of time.
+  call get_param(param_file, mod_name, "DT", dt, units="s", scale=1.0, fail_if_missing=.true.)
   call get_param(param_file, mod_name, "DT_FORCING", dt_forcing, &
                  "The time step for changing forcing, coupling with other "//&
                  "components, or potentially writing certain diagnostics. "//&
-                 "The default value is given by DT.", units="s", default=dt)
+                 "The default value is given by DT.", units="s", default=dt, scale=1.0)
   if (offline_tracer_mode) then
     call get_param(param_file, mod_name, "DT_OFFLINE", dt_forcing, &
                    "Length of time between reading in of input fields", &
-                   units='s', fail_if_missing=.true.)
+                   units="s", scale=1.0, fail_if_missing=.true.)
     dt = dt_forcing
   endif
   ntstep = MAX(1,ceiling(dt_forcing/dt - 0.001))
@@ -350,9 +352,10 @@ program MOM6
     call MOM_mesg("Using real elapsed time for the master clock.", 2)
 
   ! Determine the segment end time, either from the namelist file or parsed input file.
+  ! Note that Time_unit always is in MKS units of time, as is emphasized by the scale=1.0 argument here.
   call get_param(param_file, mod_name, "TIMEUNIT", Time_unit, &
                  "The time unit for DAYMAX, ENERGYSAVEDAYS, and RESTINT.", &
-                 units="s", default=86400.0)
+                 units="s", default=86400.0, scale=1.0)
   if (years+months+days+hours+minutes+seconds > 0) then
     Time_end = increment_date(Time, years, months, days, hours, minutes, seconds)
     call MOM_mesg('Segment run length determined from ocean_solo_nml.', 2)

src/ALE/MOM_hybgen_regrid.F90

@@ -172,11 +172,11 @@ subroutine init_hybgen_regrid(CS, GV, US, param_file)
   call get_param(param_file, mdl, "HYBGEN_REMAP_MIN_ZSTAR_DILATE", CS%min_dilate, &
                  "The maximum amount of dilation that is permitted when converting target "//&
                  "coordinates from z to z* [nondim].  This limit applies when drying occurs.", &
-                 default=0.5)
+                 units="nondim", default=0.5)
   call get_param(param_file, mdl, "HYBGEN_REMAP_MAX_ZSTAR_DILATE", CS%max_dilate, &
                  "The maximum amount of dilation that is permitted when converting target "//&
                  "coordinates from z to z* [nondim].  This limit applies when drying occurs.", &
-                 default=2.0)
+                 units="nondim", default=2.0)
 
   CS%onem = 1.0 * GV%m_to_H
 

src/core/MOM_grid.F90

@@ -75,24 +75,24 @@ module MOM_grid
 
   real ALLOCABLE_, dimension(NIMEM_,NJMEM_) :: &
     mask2dT, &   !< 0 for land points and 1 for ocean points on the h-grid [nondim].
-    geoLatT, &   !< The geographic latitude at q points in degrees of latitude or m.
-    geoLonT, &   !< The geographic longitude at q points in degrees of longitude or m.
+    geoLatT, &   !< The geographic latitude at q points [degrees_N] or [km] or [m].
+    geoLonT, &   !< The geographic longitude at q points [degrees_E] or [km] or [m].
     dxT, &       !< dxT is delta x at h points [L ~> m].
     IdxT, &      !< 1/dxT [L-1 ~> m-1].
     dyT, &       !< dyT is delta y at h points [L ~> m].
     IdyT, &      !< IdyT is 1/dyT [L-1 ~> m-1].
     areaT, &     !< The area of an h-cell [L2 ~> m2].
     IareaT, &    !< 1/areaT [L-2 ~> m-2].
     sin_rot, &   !< The sine of the angular rotation between the local model grid's northward
-                 !! and the true northward directions.
+                 !! and the true northward directions [nondim].
     cos_rot      !< The cosine of the angular rotation between the local model grid's northward
-                 !! and the true northward directions.
+                 !! and the true northward directions [nondim].
 
   real ALLOCABLE_, dimension(NIMEMB_PTR_,NJMEM_) :: &
     mask2dCu, &  !< 0 for boundary points and 1 for ocean points on the u grid [nondim].
     OBCmaskCu, & !< 0 for boundary or OBC points and 1 for ocean points on the u grid [nondim].
-    geoLatCu, &  !< The geographic latitude at u points in degrees of latitude or m.
-    geoLonCu, &  !< The geographic longitude at u points in degrees of longitude or m.
+    geoLatCu, &  !< The geographic latitude at u points [degrees_N] or [km] or [m]
+    geoLonCu, &  !< The geographic longitude at u points [degrees_E] or [km] or [m].
     dxCu, &      !< dxCu is delta x at u points [L ~> m].
     IdxCu, &     !< 1/dxCu [L-1 ~> m-1].
     dyCu, &      !< dyCu is delta y at u points [L ~> m].
@@ -104,8 +104,8 @@ module MOM_grid
   real ALLOCABLE_, dimension(NIMEM_,NJMEMB_PTR_) :: &
     mask2dCv, &  !< 0 for boundary points and 1 for ocean points on the v grid [nondim].
     OBCmaskCv, & !< 0 for boundary or OBC points and 1 for ocean points on the v grid [nondim].
-    geoLatCv, &  !< The geographic latitude at v points in degrees of latitude or m.
-    geoLonCv, &  !< The geographic longitude at v points in degrees of longitude or m.
+    geoLatCv, &  !< The geographic latitude at v points [degrees_N] or [km] or [m]
+    geoLonCv, &  !< The geographic longitude at v points [degrees_E] or [km] or [m].
     dxCv, &      !< dxCv is delta x at v points [L ~> m].
     IdxCv, &     !< 1/dxCv [L-1 ~> m-1].
     dyCv, &      !< dyCv is delta y at v points [L ~> m].
@@ -126,8 +126,8 @@ module MOM_grid
 
   real ALLOCABLE_, dimension(NIMEMB_PTR_,NJMEMB_PTR_) :: &
     mask2dBu, &  !< 0 for boundary points and 1 for ocean points on the q grid [nondim].
-    geoLatBu, &  !< The geographic latitude at q points in degrees of latitude or m.
-    geoLonBu, &  !< The geographic longitude at q points in degrees of longitude or m.
+    geoLatBu, &  !< The geographic latitude at q points [degrees_N] or [km] or [m]
+    geoLonBu, &  !< The geographic longitude at q points [degrees_E] or [km] or [m].
     dxBu, &      !< dxBu is delta x at q points [L ~> m].
     IdxBu, &     !< 1/dxBu [L-1 ~> m-1].
     dyBu, &      !< dyBu is delta y at q points [L ~> m].
@@ -181,8 +181,8 @@ module MOM_grid
 
   ! These parameters are run-time parameters that are used during some
   ! initialization routines (but not all)
-  real :: south_lat     !< The latitude (or y-coordinate) of the first v-line
-  real :: west_lon      !< The longitude (or x-coordinate) of the first u-line
+  real :: south_lat     !< The latitude (or y-coordinate) of the first v-line [degrees_N] or [km] or [m]
+  real :: west_lon      !< The longitude (or x-coordinate) of the first u-line [degrees_E] or [km] or [m]
   real :: len_lat       !< The latitudinal (or y-coord) extent of physical domain
   real :: len_lon       !< The longitudinal (or x-coord) extent of physical domain
   real :: Rad_Earth     !< The radius of the planet [m]
@@ -223,7 +223,7 @@ subroutine MOM_grid_init(G, param_file, US, HI, global_indexing, bathymetry_at_v
 
 
   ! Read all relevant parameters and write them to the model log.
-  call get_param(param_file, mod_nm, "REFERENCE_HEIGHT", G%Z_ref, default=0.0, do_not_log=.true.)
+  call get_param(param_file, mod_nm, "REFERENCE_HEIGHT", G%Z_ref, units="m", default=0.0, do_not_log=.true.)
   call log_version(param_file, mod_nm, version, &
                    "Parameters providing information about the lateral grid.", &
                    log_to_all=.true., layout=.true., all_default=(G%Z_ref==0.0))
@@ -477,8 +477,8 @@ end subroutine set_derived_metrics
 
 !> Adcroft_reciprocal(x) = 1/x for |x|>0 or 0 for x=0.
 function Adcroft_reciprocal(val) result(I_val)
-  real, intent(in) :: val  !< The value being inverted.
-  real :: I_val            !< The Adcroft reciprocal of val.
+  real, intent(in) :: val  !< The value being inverted [A].
+  real :: I_val            !< The Adcroft reciprocal of val [A-1].
 
   I_val = 0.0 ; if (val /= 0.0) I_val = 1.0/val
 end function Adcroft_reciprocal
@@ -488,12 +488,12 @@ logical function isPointInCell(G, i, j, x, y)
   type(ocean_grid_type), intent(in) :: G !< Grid type
   integer,               intent(in) :: i !< i index of cell to test
   integer,               intent(in) :: j !< j index of cell to test
-  real,                  intent(in) :: x !< x coordinate of point
-  real,                  intent(in) :: y !< y coordinate of point
+  real,                  intent(in) :: x !< x coordinate of point [degrees_E]
+  real,                  intent(in) :: y !< y coordinate of point [degrees_N]
   ! Local variables
-  real :: xNE, xNW, xSE, xSW ! Longitudes of cell corners [degLon]
-  real :: yNE, yNW, ySE, ySW ! Latitudes of cell corners [degLat]
-  real :: l0, l1, l2, l3 ! Crossed products of differences in position [degLon degLat]
+  real :: xNE, xNW, xSE, xSW ! Longitudes of cell corners [degrees_E]
+  real :: yNE, yNW, ySE, ySW ! Latitudes of cell corners [degrees_N]
+  real :: l0, l1, l2, l3 ! Crossed products of differences in position [degrees_E degrees_N]
   real :: p0, p1, p2, p3 ! Trinary unitary values reflecting the signs of the crossed products [nondim]
   isPointInCell = .false.
   xNE = G%geoLonBu(i  ,j  ) ; yNE = G%geoLatBu(i  ,j  )

src/framework/MOM_diag_mediator.F90

@@ -3228,7 +3228,7 @@ subroutine diag_mediator_init(G, GV, US, nz, param_file, diag_cs, doc_file_dir)
 
   call get_param(param_file, mdl, 'DIAG_MISVAL', diag_cs%missing_value, &
                  'Set the default missing value to use for diagnostics.', &
-                 default=1.e20)
+                 units="various", default=1.e20, scale=1.0)
   call get_param(param_file, mdl, 'DIAG_AS_CHKSUM', diag_cs%diag_as_chksum, &
                  'Instead of writing diagnostics to the diag manager, write '//&
                  'a text file containing the checksum (bitcount) of the array.',  &

src/ice_shelf/MOM_ice_shelf_dynamics.F90

@@ -149,9 +149,9 @@ module MOM_ice_shelf_dynamics
   real :: min_thickness_simple_calve !< min. ice shelf thickness criteria for calving [Z ~> m].
 
   real :: cg_tolerance !< The tolerance in the CG solver, relative to initial residual, that
-                       !! determines when to stop the conjugate gradient iterations.
+                       !! determines when to stop the conjugate gradient iterations [nondim].
   real :: nonlinear_tolerance !< The fractional nonlinear tolerance, relative to the initial error,
-                              !! that sets when to stop the iterative velocity solver
+                              !! that sets when to stop the iterative velocity solver [nondim]
   integer :: cg_max_iterations !< The maximum number of iterations that can be used in the CG solver
   integer :: nonlin_solve_err_mode  !< 1: exit vel solve based on nonlin residual
                     !! 2: exit based on "fixed point" metric (|u - u_last| / |u| < tol) where | | is infty-norm
@@ -389,7 +389,7 @@ subroutine initialize_ice_shelf_dyn(param_file, Time, ISS, CS, G, US, diag, new_
       "GROUNDING_LINE_INTERP_SUBGRID_N must be a positive integer if GL regularization is used")
     call get_param(param_file, mdl, "ICE_SHELF_CFL_FACTOR", CS%CFL_factor, &
                  "A factor used to limit timestep as CFL_FACTOR * min (\Delta x / u). "//&
-                 "This is only used with an ice-only model.", default=0.25)
+                 "This is only used with an ice-only model.", units="nondim", default=0.25)
   endif
   call get_param(param_file, mdl, "RHO_0", CS%density_ocean_avg, &
                  "avg ocean density used in floatation cond", &
@@ -414,9 +414,9 @@ subroutine initialize_ice_shelf_dyn(param_file, Time, ISS, CS, G, US, diag, new_
     call get_param(param_file, mdl, "DENSITY_ICE", CS%density_ice, &
                  "A typical density of ice.", units="kg m-3", default=917.0, scale=US%kg_m3_to_R)
     call get_param(param_file, mdl, "CONJUGATE_GRADIENT_TOLERANCE", CS%cg_tolerance, &
-                "tolerance in CG solver, relative to initial residual", default=1.e-6)
+                "tolerance in CG solver, relative to initial residual", units="nondim", default=1.e-6)
     call get_param(param_file, mdl, "ICE_NONLINEAR_TOLERANCE", CS%nonlinear_tolerance, &
-                "nonlin tolerance in iterative velocity solve",default=1.e-6)
+                "nonlin tolerance in iterative velocity solve", units="nondim", default=1.e-6)
     call get_param(param_file, mdl, "CONJUGATE_GRADIENT_MAXIT", CS%cg_max_iterations, &
                 "max iteratiions in CG solver", default=2000)
     call get_param(param_file, mdl, "THRESH_FLOAT_COL_DEPTH", CS%thresh_float_col_depth, &

src/ocean_data_assim/MOM_oda_driver.F90

@@ -219,7 +219,7 @@ subroutine init_oda(Time, G, GV, US, diag_CS, CS)
   if (CS%do_bias_adjustment) then
     call get_param(PF, mdl, "TRACER_ADJUSTMENT_FACTOR", CS%bias_adjustment_multiplier, &
        "A multiplicative scaling factor for the climatological tracer tendency adjustment ", &
-       default=1.0)
+       units="nondim", default=1.0)
   endif
   call get_param(PF, mdl, "USE_BASIN_MASK", CS%use_basin_mask, &
        "If true, add a basin mask to delineate weakly connected "//&