Merge pull request #7 from Hallberg-NOAA/more_unit_fixes

Corrected the descriptions of 60 variables

src/ALE/MOM_regridding.F90

@@ -1275,8 +1275,8 @@ subroutine build_rho_grid( G, GV, US, h, tv, dzInterface, remapCS, CS, frac_shel
                                                                     !! [H ~> m or kg m-2]
   type(remapping_CS),                           intent(in)    :: remapCS !< The remapping control structure
   type(regridding_CS),                          intent(in)    :: CS !< Regridding control structure
-  real, dimension(SZI_(G),SZJ_(G)), optional,   intent(in)    :: frac_shelf_h  !< Fractional
-                                                                    !! ice shelf coverage [nodim]
+  real, dimension(SZI_(G),SZJ_(G)), optional,   intent(in)    :: frac_shelf_h  !< Fractional ice
+                                                                    !! shelf coverage [nondim]
   ! Local variables
   integer :: nz
   integer :: i, j, k
@@ -1412,14 +1412,14 @@ subroutine build_grid_HyCOM1( G, GV, US, h, tv, h_new, dzInterface, CS, frac_she
   type(regridding_CS),                       intent(in)    :: CS !< Regridding control structure
   real, dimension(SZI_(G),SZJ_(G),CS%nk),    intent(inout) :: h_new !< New layer thicknesses [H ~> m or kg m-2]
   real, dimension(SZI_(G),SZJ_(G),CS%nk+1),  intent(inout) :: dzInterface !< Changes in interface position
-  real, dimension(SZI_(G),SZJ_(G)), optional, intent(in)   :: frac_shelf_h !< Fractional
-                                                                    !! ice shelf coverage [nodim]
+  real, dimension(SZI_(G),SZJ_(G)), optional, intent(in)   :: frac_shelf_h !< Fractional ice shelf
+                                                                    !! coverage [nondim]
 
   ! Local variables
   real, dimension(SZK_(GV)+1) :: z_col ! Source interface positions relative to the surface [H ~> m or kg m-2]
   real, dimension(CS%nk+1) :: z_col_new ! New interface positions relative to the surface [H ~> m or kg m-2]
   real, dimension(SZK_(GV)+1) :: dz_col  ! The realized change in z_col [H ~> m or kg m-2]
-  real, dimension(SZK_(GV))   :: p_col   ! Layer center pressure [Pa]
+  real, dimension(SZK_(GV))   :: p_col   ! Layer center pressure [R L2 T-2 ~> Pa]
   integer   :: i, j, k, nki
   real :: depth, nominalDepth
   real :: h_neglect, h_neglect_edge

src/core/MOM.F90

@@ -1711,7 +1711,8 @@ subroutine initialize_MOM(Time, Time_init, param_file, dirs, CS, restart_CSp, &
 
   integer :: i, j, k, is, ie, js, je, isd, ied, jsd, jed, nz
   integer :: IsdB, IedB, JsdB, JedB
-  real    :: dtbt        ! The barotropic timestep [s]
+  real    :: dtbt              ! If negative, this specifies the barotropic timestep as a fraction
+                               ! of the maximum stable value [nondim].
 
   real, allocatable, dimension(:,:)   :: eta ! free surface height or column mass [H ~> m or kg m-2]
   real, allocatable, dimension(:,:)   :: area_shelf_in ! area occupied by ice shelf [L2 ~> m2]

src/core/MOM_barotropic.F90

@@ -190,7 +190,7 @@ module MOM_barotropic
   logical :: integral_bt_cont !< If true, use the time-integrated velocity over the barotropic steps
                              !! to determine the integrated transports used to update the continuity
                              !! equation.  Otherwise the transports are the sum of the transports
-                             !! based on ]a series of instantaneous velocities and the BT_CONT_TYPE
+                             !! based on a series of instantaneous velocities and the BT_CONT_TYPE
                              !! for transports.  This is only valid if a BT_CONT_TYPE is used.
   logical :: Nonlinear_continuity !< If true, the barotropic continuity equation
                              !! uses the full ocean thickness for transport.

src/core/MOM_density_integrals.F90

@@ -802,7 +802,7 @@ subroutine int_density_dz_generic_ppm(k, tv, T_t, T_b, S_t, S_b, e, &
                                            !! subtracted out to reduce the magnitude of each of the integrals.
   real,                 intent(in)  :: rho_0 !< A density [R ~> kg m-3] or [kg m-3], that is used to calculate
                                            !! the pressure (as p~=-z*rho_0*G_e) used in the equation of state.
-  real,                 intent(in)  :: G_e !< The Earth's gravitational acceleration [m s-2]
+  real,                 intent(in)  :: G_e !< The Earth's gravitational acceleration [L2 Z-1 T-2 ~> m s-2]
   real,                 intent(in)  :: dz_subroundoff !< A minuscule thickness change [Z ~> m]
   real, dimension(SZI_(HI),SZJ_(HI)), &
                         intent(in)  :: bathyT !< The depth of the bathymetry [Z ~> m]
@@ -1457,7 +1457,7 @@ subroutine int_spec_vol_dp_generic_plm(T_t, T_b, S_t, S_b, p_t, p_b, alpha_ref,
   real :: wt_t(5), wt_b(5) ! Weights of top and bottom values at quadrature points [nondim]
   real :: T_top, T_bot, S_top, S_bot, P_top, P_bot
 
-  real :: alpha_anom ! The depth averaged specific density anomaly [m3 kg-1]
+  real :: alpha_anom ! The depth averaged specific density anomaly [R-1 ~> m3 kg-1] or [m3 kg-1]
   real :: dp         ! The pressure change through a layer [R L2 T-2 ~> Pa]
   real :: dp_90(2:4) ! The pressure change through a layer divided by 90 [R L2 T-2 ~> Pa]
   real :: hWght      ! A pressure-thickness below topography [R L2 T-2 ~> Pa]

src/core/MOM_open_boundary.F90

@@ -3730,13 +3730,16 @@ subroutine update_OBC_segment_data(G, GV, US, OBC, tv, h, Time)
   integer :: is_obc, ie_obc, js_obc, je_obc  ! segment indices within local domain
   integer :: ishift, jshift  ! offsets for staggered locations
   real, dimension(:,:,:), allocatable, target :: tmp_buffer
-  real, dimension(:), allocatable :: h_stack
+  real, dimension(:), allocatable :: h_stack  ! Thicknesses at corner points [H ~> m or kg m-2]
   integer :: is_obc2, js_obc2
-  real :: net_H_src, net_H_int, scl_fac
-  real :: tidal_vel, tidal_elev
-  real, allocatable :: normal_trans_bt(:,:)   ! barotropic transport
+  real :: net_H_src   ! Total thickness of the incoming flow in the source field [H ~> m or kg m-2]
+  real :: net_H_int   ! Total thickness of the incoming flow in the model [H ~> m or kg m-2]
+  real :: scl_fac     ! A nondimensional scaling factor [nondim]
+  real :: tidal_vel   ! Tangential tidal velocity [m s-1]
+  real :: tidal_elev  ! Tidal elevation at an OBC point [m]
+  real, allocatable :: normal_trans_bt(:,:) ! barotropic transport [H L2 T-1 ~> m3 s-1]
   integer :: turns      ! Number of index quarter turns
-  real :: time_delta  ! Time since tidal reference date
+  real :: time_delta    ! Time since tidal reference date [s]
 
   is = G%isc ; ie = G%iec ; js = G%jsc ; je = G%jec
   isd = G%isd ; ied = G%ied ; jsd = G%jsd ; jed = G%jed
@@ -5110,7 +5113,7 @@ subroutine adjustSegmentEtaToFitBathymetry(G, GV, US, segment,fld)
 
   integer :: i, j, k, is, ie, js, je, nz, contractions, dilations
   integer :: n
-  real, allocatable, dimension(:,:,:) :: eta ! Segment source data interface heights, [Z -> m]
+  real, allocatable, dimension(:,:,:) :: eta ! Segment source data interface heights [Z ~> m]
   real :: hTolerance = 0.1 !<  Tolerance to exceed adjustment criteria [Z ~> m]
   real :: hTmp, eTmp, dilate
   character(len=100) :: mesg

src/core/MOM_variables.F90

@@ -67,7 +67,7 @@ module MOM_variables
   logical :: T_is_conT = .false. !< If true, the temperature variable SST is actually the
                    !! conservative temperature in [degC].
   logical :: S_is_absS = .false. !< If true, the salinity variable SSS is actually the
-                   !! absolute salinity in [g/kg].
+                   !! absolute salinity in [gSalt kg-1].
   type(coupler_2d_bc_type) :: tr_fields !< A structure that may contain an
                 !! array of named fields describing tracer-related quantities.
        !### NOTE: ALL OF THE ARRAYS IN TR_FIELDS USE THE COUPLER'S INDEXING CONVENTION AND HAVE NO
@@ -95,7 +95,7 @@ module MOM_variables
   logical :: T_is_conT = .false. !< If true, the temperature variable tv%T is
                          !! actually the conservative temperature [degC].
   logical :: S_is_absS = .false. !< If true, the salinity variable tv%S is
-                         !! actually the absolute salinity in units of [gSalt/kg].
+                         !! actually the absolute salinity in units of [gSalt kg-1].
   real :: min_salinity = 0.01 !< The minimum value of salinity when BOUND_SALINITY=True [ppt].
                          !! The default is 0.01 for backward compatibility but should be 0.
   ! These arrays are accumulated fluxes for communication with other components.

src/diagnostics/MOM_diagnostics.F90

@@ -95,8 +95,8 @@ module MOM_diagnostics
   ! The following arrays hold diagnostics in the layer-integrated energy budget.
   real, allocatable :: KE(:,:,:)          !< KE per unit mass [L2 T-2 ~> m2 s-2]
   real, allocatable :: dKE_dt(:,:,:)      !< time derivative of the layer KE [H L2 T-3 ~> m3 s-3]
-  real, allocatable :: PE_to_KE(:,:,:)    !< potential energy to KE term [m3 s-3]
-  real, allocatable :: KE_BT(:,:,:)       !< barotropic contribution to KE term [m3 s-3]
+  real, allocatable :: PE_to_KE(:,:,:)    !< potential energy to KE term [H L2 T-3 ~> m3 s-3]
+  real, allocatable :: KE_BT(:,:,:)       !< barotropic contribution to KE term [H L2 T-3 ~> m3 s-3]
   real, allocatable :: KE_CorAdv(:,:,:)   !< KE source from the combined Coriolis and
                                           !! advection terms [H L2 T-3 ~> m3 s-3].
                                           !! The Coriolis source should be zero, but is not due to truncation
@@ -422,7 +422,7 @@ subroutine calculate_diagnostic_fields(u, v, h, uh, vh, tv, ADp, CDp, p_surf, &
     call post_data(CS%id_masso, masso, CS%diag)
   endif
 
-  ! diagnose thickness/volumes of grid cells [m]
+  ! diagnose thickness/volumes of grid cells [Z ~> m] and [m3]
   if (CS%id_thkcello>0 .or. CS%id_volcello>0) then
     if (GV%Boussinesq) then ! thkcello = h for Boussinesq
       if (CS%id_thkcello > 0) then ; if (GV%H_to_Z == 1.0) then
@@ -903,7 +903,7 @@ subroutine calculate_vertical_integrals(h, tv, p_surf, G, GV, US, CS)
               ! at the ocean surface [R L2 T-2 ~> Pa].
     dpress, & ! Change in hydrostatic pressure across a layer [R L2 T-2 ~> Pa].
     tr_int    ! vertical integral of a tracer times density,
-              ! (Rho_0 in a Boussinesq model) [TR kg m-2].
+              ! (Rho_0 in a Boussinesq model) [Conc R Z ~> Conc kg m-2].
   real    :: IG_Earth  ! Inverse of gravitational acceleration [T2 Z L-2 ~> s2 m-1].
 
   integer :: i, j, k, is, ie, js, je, nz

src/diagnostics/MOM_sum_output.F90

@@ -147,11 +147,10 @@ subroutine MOM_sum_output_init(G, GV, US, param_file, directory, ntrnc, &
   type(Sum_output_CS),     pointer       :: CS         !< A pointer that is set to point to the
                                                        !! control structure for this module.
   ! Local variables
-  real :: Time_unit ! The time unit in seconds for ENERGYSAVEDAYS.
-  real :: Rho_0     ! A reference density [kg m-3]
+  real :: Time_unit ! The time unit in seconds for ENERGYSAVEDAYS [s]
   real :: maxvel    ! The maximum permitted velocity [m s-1]
-! This include declares and sets the variable "version".
-#include "version_variable.h"
+  ! This include declares and sets the variable "version".
+# include "version_variable.h"
   character(len=40)  :: mdl = "MOM_sum_output" ! This module's name.
   character(len=200) :: energyfile  ! The name of the energy file.
   character(len=32) :: filename_appendix = '' !fms appendix to filename for ensemble runs
@@ -381,11 +380,10 @@ subroutine write_energy(u, v, h, tv, day, n, G, GV, US, CS, tracer_CSp, dt_forci
     mass_anom_EFP      ! The change in fresh water that cannot be accounted for by the surface
                        ! fluxes [kg].
   type(EFP_type), dimension(5) :: EFP_list ! An array of EFP types for joint global sums.
-  real :: CFL_Iarea    ! Direction-based inverse area used in CFL test [L-2].
+  real :: CFL_Iarea    ! Direction-based inverse area used in CFL test [L-2 ~> m-2].
   real :: CFL_trans    ! A transport-based definition of the CFL number [nondim].
   real :: CFL_lin      ! A simpler definition of the CFL number [nondim].
   real :: max_CFL(2)   ! The maxima of the CFL numbers [nondim].
-  real :: Irho0        ! The inverse of the reference density [m3 kg-1].
   real, dimension(SZI_(G),SZJ_(G),SZK_(GV)) :: &
     tmp1               ! A temporary array
   real, dimension(SZI_(G),SZJ_(G),SZK_(GV)+1) :: &
@@ -741,7 +739,6 @@ subroutine write_energy(u, v, h, tv, day, n, G, GV, US, CS, tracer_CSp, dt_forci
   if (nTr_stocks > 0) call sum_across_PEs(Tr_stocks,nTr_stocks)
 
   call max_across_PEs(max_CFL, 2)
-  Irho0 = 1.0 / (US%R_to_kg_m3*GV%Rho0)
 
   if (CS%use_temperature) then
     if (CS%previous_calls == 0) then
@@ -1038,7 +1035,7 @@ subroutine accumulate_net_input(fluxes, sfc_state, tv, dt, G, US, CS)
 !    enddo ; enddo ; endif
 
     if (associated(fluxes%salt_flux)) then ; do j=js,je ; do i=is,ie
-      ! convert salt_flux from kg (salt)/(m^2 s) to ppt * [m s-1].
+      ! integrate salt_flux in [R Z T-1 ~> kgSalt m-2 s-1] to give [ppt kg]
       salt_in(i,j) = RZL2_to_kg * dt * &
                      G%areaT(i,j)*(1000.0*fluxes%salt_flux(i,j))
     enddo ; enddo ; endif

src/diagnostics/MOM_wave_speed.F90

@@ -623,7 +623,7 @@ subroutine tdma6(n, a, c, lam, y)
     endif
     yy(k) = y(k) + a(k) * yy(k-1) * I_beta(k-1)
   enddo
-  ! The units of y change by a factor of [L2 T-2] in the following lines.
+  ! The units of y change by a factor of [L2 T-2 ~> m2 s-2] in the following lines.
   y(n) = yy(n) * I_beta(n)
   do k = n-1, 1, -1
     y(k) = ( yy(k) + c(k) * y(k+1) ) * I_beta(k)

src/initialization/MOM_coord_initialization.F90

@@ -309,13 +309,13 @@ subroutine set_coord_from_TS_range(Rlay, g_prime, GV, US, param_file, eqn_of_sta
   ! Local variables
   real, dimension(GV%ke) :: T0, S0,  Pref
   real :: S_Ref, S_Light, S_Dense ! Salinity range parameters [ppt].
-  real :: T_Ref, T_Light, T_Dense ! Temperature range parameters [decC].
+  real :: T_Ref, T_Light, T_Dense ! Temperature range parameters [degC].
   real :: res_rat ! The ratio of density space resolution in the denser part
                   ! of the range to that in the lighter part of the range.
                   ! Setting this greater than 1 increases the resolution for
-                  ! the denser water.
+                  ! the denser water [nondim].
   real :: g_fs    ! Reduced gravity across the free surface [L2 Z-1 T-2 ~> m s-2].
-  real :: a1, frac_dense, k_frac
+  real :: a1, frac_dense, k_frac  ! Nondimensional temporary variables [nondim]
   integer :: k, nz, k_light
   character(len=40)  :: mdl = "set_coord_from_TS_range" ! This subroutine's name.
   character(len=200) :: filename, coord_file, inputdir ! Strings for file/path

src/initialization/MOM_fixed_initialization.F90

@@ -144,7 +144,7 @@ subroutine MOM_initialize_fixed(G, US, OBC, PF, write_geom, output_dir)
   endif
 
 !    Calculate the value of the Coriolis parameter at the latitude   !
-!  of the q grid points [s-1].
+!  of the q grid points [T-1 ~> s-1].
   call MOM_initialize_rotation(G%CoriolisBu, G, PF, US=US)
 !   Calculate the components of grad f (beta)
   call MOM_calculate_grad_Coriolis(G%dF_dx, G%dF_dy, G, US=US)
@@ -167,13 +167,13 @@ subroutine MOM_initialize_fixed(G, US, OBC, PF, write_geom, output_dir)
 end subroutine MOM_initialize_fixed
 
 !> MOM_initialize_topography makes the appropriate call to set up the bathymetry.  At this
-!! point the topography is in units of [m], but this can be changed later.
+!! point the topography is in units of [Z ~> m] or [m], depending on the presence of US.
 subroutine MOM_initialize_topography(D, max_depth, G, PF, US)
   type(dyn_horgrid_type),           intent(in)  :: G  !< The dynamic horizontal grid type
   real, dimension(G%isd:G%ied,G%jsd:G%jed), &
-                                    intent(out) :: D  !< Ocean bottom depth [m]
+                                    intent(out) :: D  !< Ocean bottom depth [Z ~> m] or [m]
   type(param_file_type),            intent(in)  :: PF !< Parameter file structure
-  real,                             intent(out) :: max_depth !< Maximum depth of model [m]
+  real,                             intent(out) :: max_depth !< Maximum depth of model [Z ~> m] or [m]
   type(unit_scale_type),  optional, intent(in)  :: US !< A dimensional unit scaling type
 
   ! This subroutine makes the appropriate call to set up the bottom depth.

src/initialization/MOM_shared_initialization.F90

@@ -184,7 +184,8 @@ end subroutine initialize_topography_from_file
 subroutine apply_topography_edits_from_file(D, G, param_file, US)
   type(dyn_horgrid_type),           intent(in)    :: G !< The dynamic horizontal grid type
   real, dimension(G%isd:G%ied,G%jsd:G%jed), &
-                                    intent(inout) :: D !< Ocean bottom depth in m or Z if US is present
+                                    intent(inout) :: D !< Ocean bottom depth [m] or [Z ~> m] if
+                                                       !! US is present
   type(param_file_type),            intent(in)    :: param_file !< Parameter file structure
   type(unit_scale_type),  optional, intent(in)    :: US !< A dimensional unit scaling type
 

src/initialization/MOM_state_initialization.F90

@@ -1763,10 +1763,10 @@ subroutine initialize_sponges_file(G, GV, US, use_temperature, tv, u, v, depth_t
   real, allocatable, dimension(:,:,:) :: tmp_tr ! A temporary array for reading sponge fields
   real, allocatable, dimension(:,:,:) :: tmp_u,tmp_v ! A temporary array for reading sponge fields
 
-  real :: Idamp(SZI_(G),SZJ_(G))    ! The inverse damping rate [T-1 ~> s-1].
-  real :: Idamp_u(SZIB_(G),SZJ_(G)) ! The inverse damping rate for velocity fields [T-1 ~> s-1].
-  real :: Idamp_v(SZI_(G),SZJB_(G)) ! The inverse damping rate for velocity fields [T-1 ~> s-1].
-  real :: pres(SZI_(G))     ! An array of the reference pressure [R L2 T-2 ~> Pa].
+  real :: Idamp(SZI_(G),SZJ_(G))    ! The sponge damping rate [T-1 ~> s-1]
+  real :: Idamp_u(SZIB_(G),SZJ_(G)) ! The sponge damping rate for velocity fields [T-1 ~> s-1]
+  real :: Idamp_v(SZI_(G),SZJB_(G)) ! The sponge damping rate for velocity fields [T-1 ~> s-1]
+  real :: pres(SZI_(G))             ! An array of the reference pressure [R L2 T-2 ~> Pa]
 
   integer, dimension(2) :: EOSdom ! The i-computational domain for the equation of state
   integer :: i, j, k, is, ie, js, je, nz
@@ -1852,7 +1852,7 @@ subroutine initialize_sponges_file(G, GV, US, use_temperature, tv, u, v, depth_t
                  "of sponge restoring data.", default=time_space_interp_sponge)
 
 
-  ! Read in inverse damping rate for tracers
+  ! Read in sponge damping rate for tracers
   filename = trim(inputdir)//trim(damping_file)
   call log_param(param_file, mdl, "INPUTDIR/SPONGE_DAMPING_FILE", filename)
   if (.not.file_exists(filename, G%Domain)) &
@@ -1863,7 +1863,7 @@ subroutine initialize_sponges_file(G, GV, US, use_temperature, tv, u, v, depth_t
 
   call MOM_read_data(filename, Idamp_var, Idamp(:,:), G%Domain, scale=US%T_to_s)
 
-  ! Read in inverse damping rate for velocities
+  ! Read in sponge damping rate for velocities
   if (sponge_uv) then
     if (separate_idamp_for_uv()) then
       filename = trim(inputdir)//trim(uv_damping_file)
@@ -1911,7 +1911,7 @@ subroutine initialize_sponges_file(G, GV, US, use_temperature, tv, u, v, depth_t
       if (eta(i,j,K) < (eta(i,j,K+1) + GV%Angstrom_Z)) &
         eta(i,j,K) = eta(i,j,K+1) + GV%Angstrom_Z
     enddo ; enddo ; enddo
-    ! Set the inverse damping rates so that the model will know where to
+    ! Set the sponge damping rates so that the model will know where to
     ! apply the sponges, along with the interface heights.
     call initialize_sponge(Idamp, eta, G, param_file, Layer_CSp, GV)
     deallocate(eta)

src/parameterizations/lateral/MOM_MEKE.F90

@@ -80,7 +80,8 @@ module MOM_MEKE
   real :: MEKE_advection_factor !< A scaling in front of the advection of MEKE [nondim]
   real :: MEKE_topographic_beta !< Weight for how much topographic beta is considered
                                 !! when computing beta in Rhines scale [nondim]
-  real :: MEKE_restoring_rate !< Inverse of the timescale used to nudge MEKE toward its equilibrium value [s-1].
+  real :: MEKE_restoring_rate !< Inverse of the timescale used to nudge MEKE toward its
+                        !! equilibrium value [T-1 ~> s-1].
   logical :: MEKE_advection_bug !< If true, recover a bug in the calculation of the barotropic
                         !! transport for the advection of MEKE, wherein only the transports in the
                         !! deepest layer are used.