Add units to the descriptions of 141 variables

  Added units in comments describing about 141 real variables in 7 framework
modules.  All answers are bitwise identical, and only comments are changed.

src/framework/MOM_diag_remap.F90

@@ -183,7 +183,11 @@ subroutine diag_remap_configure_axes(remap_cs, GV, US, param_file)
   character(len=40)  :: mod  = "MOM_diag_remap" ! This module's name.
   character(len=8)   :: units
   character(len=34)  :: longname
-  real, allocatable, dimension(:) :: interfaces, layers
+  real, allocatable, dimension(:) :: &
+    interfaces, & ! Numerical values for interface vertical coordinates, in unscaled units
+                  ! that might be [m], [kg m-3] or [nondim], depending on the coordinate.
+    layers        ! Numerical values for layer vertical coordinates, in unscaled units
+                  ! that might be [m], [kg m-3] or [nondim], depending on the coordinate.
 
   call initialize_regridding(remap_cs%regrid_cs, GV, US, GV%max_depth, param_file, mod, &
            trim(remap_cs%vertical_coord_name), "DIAG_COORD", trim(remap_cs%diag_coord_name))

src/framework/MOM_dyn_horgrid.F90

@@ -133,16 +133,20 @@ module MOM_dyn_horgrid
     IareaBu      !< IareaBu = 1/areaBu [L-2 ~> m-2].
 
   real, pointer, dimension(:) :: gridLatT => NULL()
-        !< The latitude of T points for the purpose of labeling the output axes.
+        !< The latitude of T points for the purpose of labeling the output axes,
+        !! often in units of [degrees_N] or [km] or [m] or [gridpoints].
         !! On many grids this is the same as geoLatT.
   real, pointer, dimension(:) :: gridLatB => NULL()
-        !< The latitude of B points for the purpose of labeling the output axes.
+        !< The latitude of B points for the purpose of labeling the output axes,
+        !! often in units of [degrees_N] or [km] or [m] or [gridpoints].
         !! On many grids this is the same as geoLatBu.
   real, pointer, dimension(:) :: gridLonT => NULL()
-        !< The longitude of T points for the purpose of labeling the output axes.
+        !< The longitude of T points for the purpose of labeling the output axes,
+        !! often in units of [degrees_E] or [km] or [m] or [gridpoints].
         !! On many grids this is the same as geoLonT.
   real, pointer, dimension(:) :: gridLonB => NULL()
-        !< The longitude of B points for the purpose of labeling the output axes.
+        !< The longitude of B points for the purpose of labeling the output axes,
+        !! often in units of [degrees_E] or [km] or [m] or [gridpoints].
         !! On many grids this is the same as geoLonBu.
   character(len=40) :: &
     ! Except on a Cartesian grid, these are usually some variant of "degrees".
@@ -176,10 +180,10 @@ module MOM_dyn_horgrid
 
   ! 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 :: len_lat       !< The latitudinal (or y-coord) extent of physical domain
-  real :: len_lon       !< The longitudinal (or x-coord) extent of physical domain
+  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 [degrees_N] or [km] or [m]
+  real :: len_lon       !< The longitudinal (or x-coord) extent of physical domain [degrees_E] or [km] or [m]
   real :: Rad_Earth     !< The radius of the planet [m]
   real :: Rad_Earth_L   !< The radius of the planet in rescaled units [L ~> m]
   real :: max_depth     !< The maximum depth of the ocean [Z ~> m]
@@ -407,10 +411,10 @@ end subroutine rotate_dyn_horgrid
 !! grid, both rescaling the depths and recording the new internal depth units.
 subroutine rescale_dyn_horgrid_bathymetry(G, m_in_new_units)
   type(dyn_horgrid_type), intent(inout) :: G !< The dynamic horizontal grid type
-  real,                   intent(in)    :: m_in_new_units !< The new internal representation of 1 m depth.
+  real,                   intent(in)    :: m_in_new_units !< The new internal representation of 1 m depth [m Z-1 ~> 1]
 
   ! Local variables
-  real :: rescale
+  real :: rescale ! The inverse of m_in_new_units, used in rescaling bathymetry [Z m-1 ~> 1]
   integer :: i, j, isd, ied, jsd, jed, IsdB, IedB, JsdB, JedB
 
   isd = G%isd ; ied = G%ied ; jsd = G%jsd ; jed = G%jed
@@ -485,8 +489,8 @@ end subroutine set_derived_dyn_horgrid
 
 !> 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 in abitrary units [A ~> a]
+  real :: I_val            !< The Adcroft reciprocal of val [A-1 ~> a-1].
 
   I_val = 0.0 ; if (val /= 0.0) I_val = 1.0/val
 end function Adcroft_reciprocal

src/framework/MOM_horizontal_regridding.F90

@@ -322,7 +322,7 @@ subroutine horiz_interp_and_extrap_tracer_record(filename, varnam, recnum, G, tr
                                                      !! interpreted [a] then [A ~> a]
   real, dimension(:,:),  allocatable   :: mask_in    ! A 2-d mask for extended input grid [nondim]
 
-  real :: PI_180  ! A conversion factor from degrees to radians
+  real :: PI_180  ! A conversion factor from degrees to radians [radians degree-1]
   integer :: id, jd, kd, jdp ! Input dataset data sizes
   integer :: i, j, k
   integer, dimension(4) :: start, count
@@ -670,7 +670,7 @@ subroutine horiz_interp_and_extrap_tracer_fms_id(field, Time, G, tr_z, mask_z, &
                                                      !! on the original grid [a]
   real, dimension(:,:),  allocatable   :: mask_in    !< A 2-d mask for extended input grid [nondim]
 
-  real :: PI_180  ! A conversion factor from degrees to radians
+  real :: PI_180  ! A conversion factor from degrees to radians [radians degree-1]
   integer :: id, jd, kd, jdp ! Input dataset data sizes
   integer :: i, j, k
   real, dimension(:,:), allocatable :: x_in ! Input file longitudes [radians]

src/framework/MOM_interpolate.F90

@@ -31,12 +31,12 @@ module MOM_interpolate
 subroutine time_interp_external_0d(field, time, data_in, verbose, scale)
   type(external_field), intent(in) :: field    !< Handle for time interpolated field
   type(time_type),   intent(in)    :: time     !< The target time for the data
-  real,              intent(inout) :: data_in  !< The interpolated value
+  real,              intent(inout) :: data_in  !< The interpolated value in arbitrary units [A ~> a]
   logical, optional, intent(in)    :: verbose  !< If true, write verbose output for debugging
-  real,     optional, intent(in)    :: scale   !< A scaling factor that new values of data_in are
-                                               !! multiplied by before it is returned
-  real :: data_in_pre_scale ! The input data before rescaling
-  real :: I_scale ! The inverse of scale
+  real,    optional, intent(in)    :: scale    !< A scaling factor that new values of data_in are
+                                               !! multiplied by before it is returned [A a-1 ~> 1]
+  real :: data_in_pre_scale ! The input data before rescaling [a]
+  real :: I_scale ! The inverse of scale [a A-1 ~> 1]
 
   ! Store the input value in case the scaling factor is perfectly invertable.
   data_in_pre_scale = data_in
@@ -68,7 +68,8 @@ subroutine time_interp_external_2d(field, time, data_in, interp, &
                                    verbose, horz_interp, mask_out, turns, scale)
   type(external_field), intent(in)    :: field    !< Handle for time interpolated field
   type(time_type),      intent(in)    :: time     !< The target time for the data
-  real, dimension(:,:), intent(inout) :: data_in  !< The array in which to store the interpolated values
+  real, dimension(:,:), intent(inout) :: data_in  !< The array in which to store the interpolated
+                                                  !! values in arbitrary units [A ~> a]
   integer,    optional, intent(in)    :: interp   !< A flag indicating the temporal interpolation method
   logical,    optional, intent(in)    :: verbose  !< If true, write verbose output for debugging
   type(horiz_interp_type), &
@@ -77,11 +78,11 @@ subroutine time_interp_external_2d(field, time, data_in, interp, &
               optional, intent(out)   :: mask_out !< An array that is true where there is valid data
   integer,    optional, intent(in)    :: turns    !< Number of quarter turns to rotate the data
   real,       optional, intent(in)    :: scale    !< A scaling factor that new values of data_in are
-                                                  !! multiplied by before it is returned
+                                                  !! multiplied by before it is returned [A a-1 ~> 1]
 
-  real, allocatable :: data_in_pre_scale(:,:) ! The input data before rescaling
-  real, allocatable :: data_pre_rot(:,:)      ! The unscaled input data before rotation
-  real    :: I_scale ! The inverse of scale
+  real, allocatable :: data_in_pre_scale(:,:) ! The input data before rescaling [a]
+  real, allocatable :: data_pre_rot(:,:)      ! The unscaled input data before rotation [a]
+  real    :: I_scale ! The inverse of scale [a A-1 ~> 1]
   integer :: qturns ! The number of quarter turns to rotate the data
   integer :: i, j
 
@@ -140,7 +141,8 @@ subroutine time_interp_external_3d(field, time, data_in, interp, &
                                    verbose, horz_interp, mask_out, turns, scale)
   type(external_field), intent(in)      :: field    !< Handle for time interpolated field
   type(time_type),        intent(in)    :: time     !< The target time for the data
-  real, dimension(:,:,:), intent(inout) :: data_in  !< The array in which to store the interpolated values
+  real, dimension(:,:,:), intent(inout) :: data_in  !< The array in which to store the interpolated
+                                                    !! values in arbitrary units [A ~> a]
   integer,      optional, intent(in)    :: interp   !< A flag indicating the temporal interpolation method
   logical,      optional, intent(in)    :: verbose  !< If true, write verbose output for debugging
   type(horiz_interp_type), &
@@ -149,11 +151,11 @@ subroutine time_interp_external_3d(field, time, data_in, interp, &
                 optional, intent(out)   :: mask_out !< An array that is true where there is valid data
   integer,      optional, intent(in)    :: turns    !< Number of quarter turns to rotate the data
   real,         optional, intent(in)    :: scale    !< A scaling factor that new values of data_in are
-                                                    !! multiplied by before it is returned
+                                                    !! multiplied by before it is returned [A a-1 ~> 1]
 
-  real, allocatable :: data_in_pre_scale(:,:,:) ! The input data before rescaling
-  real, allocatable :: data_pre_rot(:,:,:)      ! The unscaled input data before rotation
-  real    :: I_scale ! The inverse of scale
+  real, allocatable :: data_in_pre_scale(:,:,:) ! The input data before rescaling [a]
+  real, allocatable :: data_pre_rot(:,:,:)      ! The unscaled input data before rotation [a]
+  real    :: I_scale ! The inverse of scale [a A-1 ~> 1]
   integer :: qturns  ! The number of quarter turns to rotate the data
   integer :: i, j, k
 

src/framework/MOM_intrinsic_functions.F90

@@ -222,7 +222,7 @@ logical function Test_cuberoot(verbose, val)
   logical, intent(in) :: verbose !< If true, write results to stdout
   real, intent(in) :: val  !< The real value to test, in arbitrary units [A]
   ! Local variables
-  real :: diff ! The difference between val and the cube root of its cube.
+  real :: diff ! The difference between val and the cube root of its cube [A].
 
   diff = val - cuberoot(val)**3
   Test_cuberoot = (abs(diff) > 2.0e-15*abs(val))

src/framework/MOM_string_functions.F90

@@ -86,7 +86,7 @@ end function left_ints
 
 !> Returns a left-justified string with a real formatted like '(G)'
 function left_real(val)
-  real, intent(in)  :: val !< The real variable to convert to a string
+  real, intent(in)  :: val !< The real variable to convert to a string, in arbitrary units [A]
   character(len=32) :: left_real !< The output string
 
   integer :: l, ind
@@ -139,7 +139,7 @@ end function left_real
 !> Returns a character string of a comma-separated, compact formatted, reals
 !! e.g. "1., 2., 5*3., 5.E2"
 function left_reals(r,sep)
-  real, intent(in) :: r(:) !< The array of real variables to convert to a string
+  real, intent(in) :: r(:) !< The array of real variables to convert to a string, in arbitrary units [A]
   character(len=*), optional, intent(in) :: sep !< The separator between
                                     !! successive values, by default it is ', '.
   character(len=:), allocatable :: left_reals !< The output string
@@ -179,10 +179,10 @@ end function left_reals
 !> Returns True if the string can be read/parsed to give the exact value of "val"
 function isFormattedFloatEqualTo(str, val)
   character(len=*), intent(in) :: str !< The string to parse
-  real,             intent(in) :: val !< The real value to compare with
+  real,             intent(in) :: val !< The real value to compare with, in arbitrary units [A]
   logical                      :: isFormattedFloatEqualTo
   ! Local variables
-  real :: scannedVal
+  real :: scannedVal ! The value extraced from str, in arbitrary units [A]
 
   isFormattedFloatEqualTo=.false.
   read(str(1:),*,err=987) scannedVal
@@ -263,12 +263,12 @@ integer function extract_integer(string, separators, n, missing_value)
 
 end function extract_integer
 
-!> Returns the real corresponding to the nth word in the argument.
+!> Returns the real corresponding to the nth word in the argument, in arbitrary units [A].
 real function extract_real(string, separators, n, missing_value)
   character(len=*), intent(in) :: string     !< String to scan
   character(len=*), intent(in) :: separators !< Characters to use for delineation
   integer,          intent(in) :: n          !< Number of word to extract
-  real, optional,   intent(in) :: missing_value !< Value to assign if word is missing
+  real, optional,   intent(in) :: missing_value !< Value to assign if word is missing, in arbitrary units [A]
   ! Local variables
   character(len=20) :: word
 
@@ -314,6 +314,7 @@ logical function string_functions_unit_tests(verbose)
   logical, intent(in) :: verbose !< If true, write results to stdout
   ! Local variables
   integer :: i(5) = (/ -1, 1, 3, 3, 0 /)
+  ! This is an array of real test values, in arbitrary units [A]
   real :: r(8) = (/ 0., 1., -2., 1.3, 3.E-11, 3.E-11, 3.E-11, -5.1E12 /)
   logical :: fail, v
   fail = .false.
@@ -387,8 +388,8 @@ end function localTestI
 !> True if r1 is not equal to r2. False otherwise.
 logical function localTestR(verbose,r1,r2)
   logical, intent(in) :: verbose !< If true, write results to stdout
-  real, intent(in) :: r1 !< Float
-  real, intent(in) :: r2 !< Float
+  real, intent(in) :: r1 !< The first value to compare, in arbitrary units [A]
+  real, intent(in) :: r2 !< The first value to compare, in arbitrary units [A]
   localTestR=.false.
   if (r1/=r2) localTestR=.true.
   if (localTestR .or. verbose) then