Add units to the descriptions of 115 variables

  Added or corrected the units in comments describing about 115 real variables
scattered across 14 tracer modules and 10 other modules.  All answers are
bitwise identical, and only comments are changed.

config_src/drivers/timing_tests/time_MOM_EOS.F90

@@ -28,9 +28,9 @@ program time_MOM_EOS
 integer, parameter :: nic=23, halo=4, nits=1000, nsamp=400
 #endif
 
-real :: times(nsamp) ! For observing the PDF
+real :: times(nsamp) ! CPU times for observing the PDF [seconds]
 
-! Arrays to hold timings:
+! Arrays to hold timings in [seconds]:
 !  first axis corresponds to the form of EOS
 !  second axis corresponds to the function being timed
 real, dimension(:,:), allocatable :: timings, tmean, tstd, tmin, tmax
@@ -100,14 +100,18 @@ subroutine run_suite(EOS_list, nic, halo, nits, timings)
   integer, intent(in)  :: nits         !< Number of calls to sample
                                        !! (large enough that the CPU timers can resolve
                                        !! the loop)
-  real,    intent(out) :: timings(n_eos,n_fns) !< The average time taken for nits calls
+  real,    intent(out) :: timings(n_eos,n_fns) !< The average time taken for nits calls [seconds]
                                        !! First index corresponds to EOS
                                        !! Second index: 1 = scalar args,
                                        !! 2 = array args without halo,
                                        !! 3 = array args with halo and "dom".
   type(EOS_type) :: EOS
   integer :: e, i, dom(2)
-  real :: start, finish, T, S, P, rho
+  real :: start, finish  ! CPU times [seconds]
+  real :: T  ! A potential or conservative temperature [degC]
+  real :: S  ! A practical salinity or absolute salinity [ppt]
+  real :: P  ! A pressure [Pa]
+  real :: rho ! A density [kg m-3] or specific volume [m3 kg-1]
   real, dimension(nic+2*halo) :: T1, S1, P1, rho1
 
   T = 10.
@@ -171,15 +175,18 @@ subroutine run_one(EOS_list, nic, halo, nits, timing)
   integer, intent(in)  :: nits         !< Number of calls to sample
                                        !! (large enough that the CPU timers can resolve
                                        !! the loop)
-  real,    intent(out) :: timing       !< The average time taken for nits calls
+  real,    intent(out) :: timing       !< The average time taken for nits calls [seconds]
                                        !! First index corresponds to EOS
                                        !! Second index: 1 = scalar args,
                                        !! 2 = array args without halo,
                                        !! 3 = array args with halo and "dom".
   type(EOS_type) :: EOS
   integer :: i, dom(2)
-  real :: start, finish
-  real, dimension(nic+2*halo) :: T1, S1, P1, rho1
+  real :: start, finish  ! CPU times [seconds]
+  real, dimension(nic+2*halo) :: T1   ! Potential or conservative temperatures [degC]
+  real, dimension(nic+2*halo) :: S1   ! A practical salinities or absolute salinities [ppt]
+  real, dimension(nic+2*halo) :: P1   ! Pressures [Pa]
+  real, dimension(nic+2*halo) :: rho1 ! Densities [kg m-3] or specific volumes [m3 kg-1]
 
   ! Time the scalar interface
   call EOS_manual_init(EOS, form_of_EOS=EOS_list(5), &

src/ALE/coord_adapt.F90

@@ -93,10 +93,10 @@ subroutine set_adapt_params(CS, adaptTimeRatio, adaptAlpha, adaptZoom, adaptZoom
   type(adapt_CS),    pointer    :: CS  !< The control structure for this module
   real,    optional, intent(in) :: adaptTimeRatio !< Ratio of optimisation and diffusion timescales [nondim]
   real,    optional, intent(in) :: adaptAlpha     !< Nondimensional coefficient determining
-                                                  !! how much optimisation to apply
+                                                  !! how much optimisation to apply [nondim]
   real,    optional, intent(in) :: adaptZoom      !< Near-surface zooming depth [H ~> m or kg m-2]
   real,    optional, intent(in) :: adaptZoomCoeff !< Near-surface zooming coefficient [nondim]
-  real,    optional, intent(in) :: adaptBuoyCoeff !< Stratification-dependent diffusion coefficient
+  real,    optional, intent(in) :: adaptBuoyCoeff !< Stratification-dependent diffusion coefficient [nondim]
   real,    optional, intent(in) :: adaptDrho0  !< Reference density difference for
                                                !! stratification-dependent diffusion [R ~> kg m-3]
   logical, optional, intent(in) :: adaptDoMin  !< If true, form a HYCOM1-like mixed layer by

src/ALE/regrid_interp.F90

@@ -305,7 +305,7 @@ subroutine interpolate_grid( n0, h0, x0, ppoly0_E, ppoly0_coefs, &
 
   ! Local variables
   integer        :: k ! loop index
-  real           :: t ! current interface target density
+  real           :: t ! current interface target density [A]
 
   ! Make sure boundary coordinates of new grid coincide with boundary
   ! coordinates of previous grid
@@ -385,10 +385,10 @@ function get_polynomial_coordinate( N, h, x_g, edge_values, ppoly_coefs, &
   ! Local variables
   real                        :: xi0         ! normalized target coordinate [nondim]
   real, dimension(DEGREE_MAX) :: a           ! polynomial coefficients [A]
-  real                        :: numerator
-  real                        :: denominator
+  real                        :: numerator   ! The numerator of an expression [A]
+  real                        :: denominator ! The denominator of an expression [A]
   real                        :: delta       ! Newton-Raphson increment [nondim]
-!   real                        :: x           ! global target coordinate
+!   real                        :: x           ! global target coordinate [nondim]
   real                        :: eps         ! offset used to get away from boundaries [nondim]
   real                        :: grad        ! gradient during N-R iterations [A]
   integer :: i, k, iter  ! loop indices

src/core/MOM_open_boundary.F90

@@ -5028,7 +5028,7 @@ subroutine mask_outside_OBCs(G, US, param_file, OBC)
   integer, parameter :: cin = 3, cout = 4, cland = -1, cedge = -2
   character(len=256) :: mesg    ! Message for error messages.
   real, allocatable, dimension(:,:) :: color, color2  ! For sorting inside from outside,
-                                                      ! two different ways
+                                                      ! two different ways [nondim]
 
   if (.not. associated(OBC)) return
 
@@ -5136,7 +5136,7 @@ end subroutine mask_outside_OBCs
 !> flood the cin, cout values
 subroutine flood_fill(G, color, cin, cout, cland)
   type(dyn_horgrid_type), intent(inout) :: G      !< Ocean grid structure
-  real, dimension(:,:),   intent(inout) :: color  !< For sorting inside from outside
+  real, dimension(:,:),   intent(inout) :: color  !< For sorting inside from outside [nondim]
   integer, intent(in) :: cin    !< color for inside the domain
   integer, intent(in) :: cout   !< color for outside the domain
   integer, intent(in) :: cland  !< color for inside the land mask
@@ -5196,7 +5196,7 @@ end subroutine flood_fill
 !> flood the cin, cout values
 subroutine flood_fill2(G, color, cin, cout, cland)
   type(dyn_horgrid_type), intent(inout) :: G       !< Ocean grid structure
-  real, dimension(:,:),   intent(inout) :: color   !< For sorting inside from outside
+  real, dimension(:,:),   intent(inout) :: color   !< For sorting inside from outside [nondim]
   integer, intent(in) :: cin    !< color for inside the domain
   integer, intent(in) :: cout   !< color for outside the domain
   integer, intent(in) :: cland  !< color for inside the land mask
@@ -5394,7 +5394,10 @@ subroutine update_segment_tracer_reservoirs(G, GV, uhr, vhr, h, OBC, dt, Reg)
                           ! For salinity the units would be [ppt S-1 ~> 1]
   integer :: i, j, k, m, n, ntr, nz, ntr_id, fd_id
   integer :: ishift, idir, jshift, jdir
-  real :: resrv_lfac_out, resrv_lfac_in
+  real :: resrv_lfac_out  ! The reservoir inverse length scale scaling factor for the outward
+                          ! direction per field [nondim]
+  real :: resrv_lfac_in   ! The reservoir inverse length scale scaling factor for the inward
+                          ! direction per field [nondim]
   real :: b_in, b_out     ! The 0 and 1 switch for tracer reservoirs
                           ! 1 if the length scale of reservoir is zero [nondim]
   real :: a_in, a_out     ! The 0 and 1(-1) switch for reservoir source weights

src/diagnostics/MOM_spatial_means.F90

@@ -166,7 +166,7 @@ function global_area_integral(var, G, scale, area, tmp_scale)
   ! In the following comments, [A] is used to indicate the arbitrary, possibly rescaled units of the
   ! input array while [a] indicates the unscaled (e.g., mks) units that can be used with the reproducing sums
   real, dimension(SZI_(G),SZJ_(G)) :: tmpForSumming ! An unscaled cell integral [a m2]
-  real :: scalefac  ! An overall scaling factor for the areas and variable.
+  real :: scalefac  ! An overall scaling factor for the areas and variable, perhaps in [m2 a A-1 L-2 ~> 1]
   real :: temp_scale ! A temporary scaling factor [a A-1 ~> 1] or [1]
   integer :: i, j, is, ie, js, je
   is = G%isc ; ie = G%iec ; js = G%jsc ; je = G%jec
@@ -493,7 +493,7 @@ subroutine global_j_mean(array, j_mean, G, mask, scale, tmp_scale)
                                                             !! arbitrary, possibly rescaled units [A ~> a]
   real, dimension(SZI_(G)),         intent(out)   :: j_mean !<  Global mean of array along its j-axis [a] or [A ~> a]
   real, dimension(SZI_(G),SZJ_(G)), &
-                          optional, intent(in)    :: mask  !< An array used for weighting the j-mean
+                          optional, intent(in)    :: mask  !< An array used for weighting the j-mean [nondim]
   real,                   optional, intent(in)    :: scale !< A rescaling factor for the output variable [a A-1 ~> 1]
                                                            !! that converts it back to unscaled (e.g., mks)
                                                            !! units to enable the use of the reproducing sums

src/parameterizations/lateral/MOM_hor_visc.F90

@@ -2973,7 +2973,7 @@ end subroutine smooth_x9_h
 !! input fields have valid values in the first two halo points upon entry.
 subroutine smooth_x9_uv(G, field_u, field_v, zero_land)
   type(ocean_grid_type),             intent(in)    :: G         !< Ocean grid
-  real, dimension(SZIB_(G),SZJ_(G)), intent(inout) :: field_u   !< u-point field to be smoothed[arbitrary]
+  real, dimension(SZIB_(G),SZJ_(G)), intent(inout) :: field_u   !< u-point field to be smoothed [arbitrary]
   real, dimension(SZI_(G),SZJB_(G)), intent(inout) :: field_v   !< v-point field to be smoothed [arbitrary]
   logical,                 optional, intent(in)    :: zero_land !< If present and false, return the average
                                                                 !! of the surrounding ocean points when

src/parameterizations/lateral/MOM_internal_tides.F90

@@ -146,15 +146,20 @@ module MOM_internal_tides
                         !< The internal wave energy density as a function of (i,j,angle,frequency,mode)
                         !! integrated within an angular and frequency band [R Z3 T-2 ~> J m-2]
   real, allocatable :: En_restart_mode1(:,:,:,:)
-                        !< The internal wave energy density as a function of (i,j,angle,freq) for mode 1
+                        !< The internal wave energy density as a function of (i,j,angle,freq)
+                        !! for mode 1 [R Z3 T-2 ~> J m-2]
   real, allocatable :: En_restart_mode2(:,:,:,:)
-                        !< The internal wave energy density as a function of (i,j,angle,freq) for mode 2
+                        !< The internal wave energy density as a function of (i,j,angle,freq)
+                        !! for mode 2 [R Z3 T-2 ~> J m-2]
   real, allocatable :: En_restart_mode3(:,:,:,:)
-                        !< The internal wave energy density as a function of (i,j,angle,freq) for mode 3
+                        !< The internal wave energy density as a function of (i,j,angle,freq)
+                        !! for mode 3 [R Z3 T-2 ~> J m-2]
   real, allocatable :: En_restart_mode4(:,:,:,:)
-                        !< The internal wave energy density as a function of (i,j,angle,freq) for mode 4
+                        !< The internal wave energy density as a function of (i,j,angle,freq)
+                        !! for mode 4 [R Z3 T-2 ~> J m-2]
   real, allocatable :: En_restart_mode5(:,:,:,:)
-                        !< The internal wave energy density as a function of (i,j,angle,freq) for mode 5
+                        !< The internal wave energy density as a function of (i,j,angle,freq)
+                        !! for mode 5 [R Z3 T-2 ~> J m-2]
 
   real, allocatable, dimension(:) :: frequency  !< The frequency of each band [T-1 ~> s-1].
 
@@ -1795,9 +1800,9 @@ subroutine propagate_y(En, speed_y, Cgy_av, dCgy, dt, G, US, Nangle, CS, LB, res
   real, dimension(G%isd:G%ied,G%JsdB:G%JedB),      &
                            intent(in)    :: speed_y !< The magnitude of the group velocity at the
                                                !! Cv points [L T-1 ~> m s-1].
-  real, dimension(Nangle), intent(in)    :: Cgy_av !< The average y-projection in each angular band.
+  real, dimension(Nangle), intent(in)    :: Cgy_av !< The average y-projection in each angular band [nondim]
   real, dimension(Nangle), intent(in)    :: dCgy !< The difference in y-projections between the
-                                               !! edges of each angular band.
+                                               !! edges of each angular band [nondim]
   real,                    intent(in)    :: dt !< Time increment [T ~> s].
   type(unit_scale_type),   intent(in)    :: US !< A dimensional unit scaling type
   type(int_tide_CS),       intent(in)    :: CS !< Internal tide control structure
@@ -2425,7 +2430,7 @@ subroutine register_int_tide_restarts(G, US, param_file, CS, restart_CS)
   character(64) :: var_name, cfr
 
   type(axis_info) :: axes_inttides(2)
-  real, dimension(:), allocatable :: angles, freqs
+  real, dimension(:), allocatable :: angles, freqs ! Lables for angles and frequencies [nondim]
 
   isd = G%isd ; ied = G%ied ; jsd = G%jsd ; jed = G%jed
 

src/parameterizations/lateral/MOM_mixed_layer_restrat.F90

@@ -1936,12 +1936,12 @@ end function mixedlayer_restrat_unit_tests
 !> Returns true if any cell of u and u_true are not identical. Returns false otherwise.
 logical function test_answer(verbose, u, u_true, label, tol)
   logical,            intent(in) :: verbose !< If true, write results to stdout
-  real,               intent(in) :: u      !< Values to test
-  real,               intent(in) :: u_true !< Values to test against (correct answer)
+  real,               intent(in) :: u      !< Values to test in arbitrary units [A]
+  real,               intent(in) :: u_true !< Values to test against (correct answer) [A]
   character(len=*),   intent(in) :: label  !< Message
-  real, optional,     intent(in) :: tol    !< The tolerance for differences between u and u_true
+  real, optional,     intent(in) :: tol    !< The tolerance for differences between u and u_true [A]
   ! Local variables
-  real :: tolerance ! The tolerance for differences between u and u_true
+  real :: tolerance ! The tolerance for differences between u and u_true [A]
   integer :: k
 
   tolerance = 0.0 ; if (present(tol)) tolerance = tol

src/parameterizations/stochastic/MOM_stochastics.F90

@@ -35,9 +35,9 @@ module MOM_stochastics
   integer :: id_epbl2_wts = -1 !< Diagnostic id for epbl dissipation perturbation
   ! stochastic patterns
   real, allocatable :: sppt_wts(:,:)  !< Random pattern for ocean SPPT
-                                     !! tendencies with a number between 0 and 2
-  real, allocatable :: epbl1_wts(:,:) !< Random pattern for K.E. generation
-  real, allocatable :: epbl2_wts(:,:) !< Random pattern for K.E. dissipation
+                                      !! tendencies with a number between 0 and 2 [nondim]
+  real, allocatable :: epbl1_wts(:,:) !< Random pattern for K.E. generation [nondim]
+  real, allocatable :: epbl2_wts(:,:) !< Random pattern for K.E. dissipation [nondim]
   type(diag_ctrl), pointer :: diag   !< structure used to regulate timing of diagnostic output
   type(time_type), pointer :: Time !< Pointer to model time (needed for sponges)
 end type stochastic_CS

src/parameterizations/vertical/MOM_vert_friction.F90

@@ -551,12 +551,12 @@ subroutine vertFPmix(ui, vi, uold, vold, hbl_h, h, forces, dt, G, GV, US, CS, OB
 
 end subroutine vertFPmix
 
-!> Returns the empirical shape-function given sigma.
+!> Returns the empirical shape-function given sigma [nondim]
 real function G_sig(sigma)
-  real , intent(in) :: sigma   !< non-dimensional normalized boundary layer depth [m]
+  real , intent(in) :: sigma    !< Normalized boundary layer depth [nondim]
 
   ! local variables
-  real :: p1, c2, c3  !< parameters used to fit and match empirycal shape-functions.
+  real :: p1, c2, c3  !< Parameters used to fit and match empirical shape-functions [nondim]
 
   ! parabola
   p1 = 0.287

src/tracer/ISOMIP_tracer.F90

@@ -45,8 +45,8 @@ module ISOMIP_tracer
   character(len = 200) :: tracer_IC_file !< The full path to the IC file, or " " to initialize internally.
   type(time_type), pointer :: Time !< A pointer to the ocean model's clock.
   type(tracer_registry_type), pointer :: tr_Reg => NULL() !< A pointer to the MOM tracer registry
-  real, pointer :: tr(:,:,:,:) => NULL()   !< The array of tracers used in this package, in g m-3?
-  real :: land_val(NTR) = -1.0 !< The value of tr used where land is masked out.
+  real, pointer :: tr(:,:,:,:) => NULL()   !< The array of tracers used in this package, in [conc] (g m-3)?
+  real :: land_val(NTR) = -1.0 !< The value of tr used where land is masked out [conc].
   logical :: use_sponge    !< If true, sponges may be applied somewhere in the domain.
 
   integer, dimension(NTR) :: ind_tr !< Indices returned by atmos_ocn_coupler_flux
@@ -80,7 +80,7 @@ function register_ISOMIP_tracer(HI, GV, param_file, CS, tr_Reg, restart_CS)
   character(len=200) :: inputdir
   character(len=48)  :: flux_units ! The units for tracer fluxes, usually
                             ! kg(tracer) kg(water)-1 m3 s-1 or kg(tracer) s-1.
-  real, pointer :: tr_ptr(:,:,:) => NULL()
+  real, pointer :: tr_ptr(:,:,:) => NULL() ! The tracer concentration [conc]
   logical :: register_ISOMIP_tracer
   integer :: isd, ied, jsd, jed, nz, m
   isd = HI%isd ; ied = HI%ied ; jsd = HI%jsd ; jed = HI%jed ; nz = GV%ke