Document remapping function variable units

  Added or amended comments to document the mostly arbitrary units of about 360
variables in 13 low-level remapping modules.  Only comments are changed and
all answers are bitwise identical.

src/ALE/MOM_hybgen_regrid.F90

@@ -41,8 +41,10 @@ module MOM_hybgen_regrid
     dp0k, & !< minimum deep    z-layer separation [H ~> m or kg m-2]
     ds0k    !< minimum shallow z-layer separation [H ~> m or kg m-2]
 
-  real :: coord_scale = 1.0     !< A scaling factor to restores the depth coordinates to values in m
-  real :: Rho_coord_scale = 1.0 !< A scaling factor to restores the denesity coordinates to values in kg m-3
+  real :: coord_scale = 1.0     !< A scaling factor to restores the depth coordinates to
+                                !! values in m [m H-1 ~> 1 or m3 kg-1]
+  real :: Rho_coord_scale = 1.0 !< A scaling factor to restores the denesity coordinates to
+                                !! values in kg m-3 [kg m-3 R-1 ~> 1]
 
   real :: dpns  !< depth to start terrain following [H ~> m or kg m-2]
   real :: dsns  !< depth to stop terrain following [H ~> m or kg m-2]
@@ -68,7 +70,7 @@ module MOM_hybgen_regrid
                      !! the bottom that certain adjustments can be made in the Hybgen regridding
                      !! code [H ~> m or kg m-2].  In Hycom, this is set to onem (nominally 1 m).
   real :: h_thin     !< A layer thickness below which a layer is considered to be too thin for
-                     !! certain adjustments to be made in the Hybgen regridding code.
+                     !! certain adjustments to be made in the Hybgen regridding code [H ~> m or kg m-2].
                      !! In Hycom, this is set to onemm (nominally 0.001 m).
 
   real :: rho_eps    !< A small nonzero density that is used to prevent division by zero
@@ -284,7 +286,7 @@ subroutine get_hybgen_regrid_params(CS, nk, ref_pressure, hybiso, nsigma, dp00i,
   real,    optional, intent(out) :: ref_pressure !< Reference pressure for density calculations [R L2 T-2 ~> Pa]
   real,    optional, intent(out) :: hybiso  !< Hybgen uses PCM if layer is within hybiso of target density [R ~> kg m-3]
   integer, optional, intent(out) :: nsigma  !< Number of sigma levels used by HYBGEN
-  real,    optional, intent(out) :: dp00i   !< Deep isopycnal spacing minimum thickness (m)
+  real,    optional, intent(out) :: dp00i   !< Deep isopycnal spacing minimum thickness [H ~> m or kg m-2]
   real,    optional, intent(out) :: qhybrlx !< Fractional relaxation amount per timestep, 0 < qyhbrlx <= 1 [nondim]
   real,    optional, intent(out) :: dp0k(:) !< minimum deep    z-layer separation [H ~> m or kg m-2]
   real,    optional, intent(out) :: ds0k(:) !< minimum shallow z-layer separation [H ~> m or kg m-2]
@@ -687,8 +689,8 @@ real function cushn(delp, dp0)
   ! These are derivative nondimensional parameters.
   ! real, parameter :: cusha = qqmn**2 * (qqmx-1.0) / (qqmx-qqmn)**2
   ! real, parameter :: I_qqmn = 1.0 / qqmn
-  real, parameter :: qq_scale = (qqmx-1.0) / (qqmx-qqmn)**2
-  real, parameter :: I_qqmx = 1.0 / qqmx
+  real, parameter :: qq_scale = (qqmx-1.0) / (qqmx-qqmn)**2  ! A scaling factor based on qqmn and qqmx [nondim]
+  real, parameter :: I_qqmx = 1.0 / qqmx  ! The inverse of qqmx [nondim]
 
   ! --- if delp >= qqmx*dp0 >>  dp0, cushn returns delp.
   ! --- if delp <= qqmn*dp0 << -dp0, cushn returns dp0.

src/ALE/MOM_hybgen_remap.F90

@@ -126,7 +126,7 @@ subroutine hybgen_ppm_coefs(s, h_src, edges, nk, ns, thin, PCM_lay)
   real :: da        ! Difference between the unlimited scalar edge value estimates [A]
   real :: a6        ! Scalar field differences that are proportional to the curvature [A]
   real :: slk, srk  ! Differences between adjacent cell averages of scalars [A]
-  real :: sck       ! Scalar differences across a cell.
+  real :: sck       ! Scalar differences across a cell [A]
   real :: as(nk)    ! Scalar field difference across each cell [A]
   real :: al(nk), ar(nk)   ! Scalar field at the left and right edges of a cell [A]
   real :: h112(nk+1), h122(nk+1)  ! Combinations of thicknesses [H ~> m or kg m-2]

src/ALE/MOM_remapping.F90

@@ -1723,7 +1723,7 @@ logical function test_interp(verbose, msg, nsrc, h_src, u_src, ndest, h_dest, u_
   ! Local variables
   real, dimension(ndest+1) :: u_dest ! Interpolated value at destination cell interfaces [A]
   integer :: k
-  real :: error
+  real :: error ! The difference between the evaluated and expected solutions [A]
 
   ! Interpolate from src to dest
   call interpolate_column(nsrc, h_src, u_src, ndest, h_dest, u_dest, .true.)
@@ -1760,7 +1760,7 @@ logical function test_reintegrate(verbose, msg, nsrc, h_src, uh_src, ndest, h_de
   ! Local variables
   real, dimension(ndest) :: uh_dest ! Reintegrated value on destination cells [A H]
   integer :: k
-  real :: error
+  real :: error  ! The difference between the evaluated and expected solutions [A H]
 
   ! Interpolate from src to dest
   call reintegrate_column(nsrc, h_src, uh_src, ndest, h_dest, uh_dest)

src/ALE/P1M_functions.F90

@@ -36,7 +36,7 @@ subroutine P1M_interpolation( N, h, u, edge_values, ppoly_coef, h_neglect, answe
 
   ! Local variables
   integer   :: k            ! loop index
-  real      :: u0_l, u0_r   ! edge values (left and right)
+  real      :: u0_l, u0_r   ! edge values (left and right) [A]
 
   ! Bound edge values (routine found in 'edge_values.F90')
   call bound_edge_values( N, h, u, edge_values, h_neglect, answer_date=answer_date )
@@ -74,10 +74,10 @@ subroutine P1M_boundary_extrapolation( N, h, u, edge_values, ppoly_coef )
   real, dimension(:,:), intent(inout) :: ppoly_coef !< coefficients of piecewise polynomials, mainly [A]
 
   ! Local variables
-  real          :: u0, u1               ! cell averages
-  real          :: h0, h1               ! corresponding cell widths
-  real          :: slope                ! retained PLM slope
-  real          :: u0_l, u0_r           ! edge values
+  real          :: u0, u1               ! cell averages [A]
+  real          :: h0, h1               ! corresponding cell widths [H]
+  real          :: slope                ! retained PLM slope [A]
+  real          :: u0_l, u0_r           ! edge values [A]
 
   ! -----------------------------------------
   ! Left edge value in the left boundary cell

src/ALE/PCM_functions.F90

@@ -17,11 +17,11 @@ module PCM_functions
 !! defining 'grid' and 'ppoly'. No consistency check is performed.
 subroutine PCM_reconstruction( N, u, edge_values, ppoly_coef )
   integer,              intent(in)    :: N !< Number of cells
-  real, dimension(:),   intent(in)    :: u !< cell averages
+  real, dimension(:),   intent(in)    :: u !< cell averages in arbitrary units [A]
   real, dimension(:,:), intent(inout) :: edge_values !< Edge value of polynomial,
-                                           !! with the same units as u.
+                                           !! with the same units as u [A].
   real, dimension(:,:), intent(inout) :: ppoly_coef !< Coefficients of polynomial,
-                                           !! with the same units as u.
+                                           !! with the same units as u [A].
 
   ! Local variables
   integer :: k

src/ALE/PLM_functions.F90

@@ -16,20 +16,21 @@ module PLM_functions
 
 contains
 
-!> Returns a limited PLM slope following White and Adcroft, 2008. [units of u]
+!> Returns a limited PLM slope following White and Adcroft, 2008, in the same arbitrary
+!! units [A] as the input values.
 !! Note that this is not the same as the Colella and Woodward method.
 real elemental pure function PLM_slope_wa(h_l, h_c, h_r, h_neglect, u_l, u_c, u_r)
-  real, intent(in) :: h_l !< Thickness of left cell [units of grid thickness]
-  real, intent(in) :: h_c !< Thickness of center cell [units of grid thickness]
-  real, intent(in) :: h_r !< Thickness of right cell [units of grid thickness]
-  real, intent(in) :: h_neglect !< A negligible thickness [units of grid thickness]
-  real, intent(in) :: u_l !< Value of left cell [units of u]
-  real, intent(in) :: u_c !< Value of center cell [units of u]
-  real, intent(in) :: u_r !< Value of right cell [units of u]
+  real, intent(in) :: h_l !< Thickness of left cell in arbitrary grid thickness units [H]
+  real, intent(in) :: h_c !< Thickness of center cell in arbitrary grid thickness units [H]
+  real, intent(in) :: h_r !< Thickness of right cell in arbitrary grid thickness units [H]
+  real, intent(in) :: h_neglect !< A negligible thickness [H]
+  real, intent(in) :: u_l !< Value of left cell in arbitrary units [A]
+  real, intent(in) :: u_c !< Value of center cell in arbitrary units [A]
+  real, intent(in) :: u_r !< Value of right cell in arbitrary units [A]
   ! Local variables
   real :: sigma_l, sigma_c, sigma_r ! Left, central and right slope estimates as
-                                    ! differences across the cell [units of u]
-  real :: u_min, u_max ! Minimum and maximum value across cell [units of u]
+                                    ! differences across the cell [A]
+  real :: u_min, u_max ! Minimum and maximum value across cell [A]
 
   ! Side differences
   sigma_r = u_r - u_c
@@ -63,20 +64,21 @@ real elemental pure function PLM_slope_wa(h_l, h_c, h_r, h_neglect, u_l, u_c, u_
 
 end function PLM_slope_wa
 
-!> Returns a limited PLM slope following Colella and Woodward 1984.
+!> Returns a limited PLM slope following Colella and Woodward 1984, in the same
+!! arbitrary units as the input values [A].
 real elemental pure function PLM_slope_cw(h_l, h_c, h_r, h_neglect, u_l, u_c, u_r)
-  real, intent(in) :: h_l !< Thickness of left cell [units of grid thickness]
-  real, intent(in) :: h_c !< Thickness of center cell [units of grid thickness]
-  real, intent(in) :: h_r !< Thickness of right cell [units of grid thickness]
-  real, intent(in) :: h_neglect !< A negligible thickness [units of grid thickness]
-  real, intent(in) :: u_l !< Value of left cell [units of u]
-  real, intent(in) :: u_c !< Value of center cell [units of u]
-  real, intent(in) :: u_r !< Value of right cell [units of u]
+  real, intent(in) :: h_l !< Thickness of left cell in arbitrary grid thickness units [H]
+  real, intent(in) :: h_c !< Thickness of center cell in arbitrary grid thickness units [H]
+  real, intent(in) :: h_r !< Thickness of right cell in arbitrary grid thickness units [H]
+  real, intent(in) :: h_neglect !< A negligible thickness [H]
+  real, intent(in) :: u_l !< Value of left cell in arbitrary units [A]
+  real, intent(in) :: u_c !< Value of center cell in arbitrary units [A]
+  real, intent(in) :: u_r !< Value of right cell in arbitrary units [A]
   ! Local variables
   real :: sigma_l, sigma_c, sigma_r ! Left, central and right slope estimates as
-                                    ! differences across the cell [units of u]
-  real :: u_min, u_max ! Minimum and maximum value across cell [units of u]
-  real :: h_cn ! Thickness of center cell [units of grid thickness]
+                                    ! differences across the cell [A]
+  real :: u_min, u_max ! Minimum and maximum value across cell [A]
+  real :: h_cn ! Thickness of center cell [H]
 
   h_cn = h_c + h_neglect
 
@@ -117,18 +119,19 @@ real elemental pure function PLM_slope_cw(h_l, h_c, h_r, h_neglect, u_l, u_c, u_
 
 end function PLM_slope_cw
 
-!> Returns a limited PLM slope following Colella and Woodward 1984.
+!> Returns a limited PLM slope following Colella and Woodward 1984, in the same
+!! arbitrary units as the input values [A].
 real elemental pure function PLM_monotonized_slope(u_l, u_c, u_r, s_l, s_c, s_r)
-  real, intent(in) :: u_l !< Value of left cell [units of u]
-  real, intent(in) :: u_c !< Value of center cell [units of u]
-  real, intent(in) :: u_r !< Value of right cell [units of u]
-  real, intent(in) :: s_l !< PLM slope of left cell [units of u]
-  real, intent(in) :: s_c !< PLM slope of center cell [units of u]
-  real, intent(in) :: s_r !< PLM slope of right cell [units of u]
+  real, intent(in) :: u_l !< Value of left cell in arbitrary units [A]
+  real, intent(in) :: u_c !< Value of center cell in arbitrary units [A]
+  real, intent(in) :: u_r !< Value of right cell in arbitrary units [A]
+  real, intent(in) :: s_l !< PLM slope of left cell [A]
+  real, intent(in) :: s_c !< PLM slope of center cell [A]
+  real, intent(in) :: s_r !< PLM slope of right cell [A]
   ! Local variables
-  real :: e_r, e_l, edge ! Right, left and temporary edge values [units of u]
-  real :: almost_two ! The number 2, almost.
-  real :: slp ! Magnitude of PLM central slope [units of u]
+  real :: e_r, e_l, edge ! Right, left and temporary edge values [A]
+  real :: almost_two ! The number 2, almost [nondim]
+  real :: slp ! Magnitude of PLM central slope [A]
 
   almost_two = 2. * ( 1. - epsilon(s_c) )
 
@@ -155,17 +158,18 @@ real elemental pure function PLM_monotonized_slope(u_l, u_c, u_r, s_l, s_c, s_r)
 
 end function PLM_monotonized_slope
 
-!> Returns a PLM slope using h2 extrapolation from a cell to the left.
+!> Returns a PLM slope using h2 extrapolation from a cell to the left, in the same
+!! arbitrary units as the input values [A].
 !! Use the negative to extrapolate from the cell to the right.
 real elemental pure function PLM_extrapolate_slope(h_l, h_c, h_neglect, u_l, u_c)
-  real, intent(in) :: h_l !< Thickness of left cell [units of grid thickness]
-  real, intent(in) :: h_c !< Thickness of center cell [units of grid thickness]
-  real, intent(in) :: h_neglect !< A negligible thickness [units of grid thickness]
-  real, intent(in) :: u_l !< Value of left cell [units of u]
-  real, intent(in) :: u_c !< Value of center cell [units of u]
+  real, intent(in) :: h_l !< Thickness of left cell in arbitrary grid thickness units [H]
+  real, intent(in) :: h_c !< Thickness of center cell in arbitrary grid thickness units [H]
+  real, intent(in) :: h_neglect !< A negligible thickness [H]
+  real, intent(in) :: u_l !< Value of left cell in arbitrary units [A]
+  real, intent(in) :: u_c !< Value of center cell in arbitrary units [A]
   ! Local variables
-  real :: left_edge ! Left edge value [units of u]
-  real :: hl, hc ! Left and central cell thicknesses [units of grid thickness]
+  real :: left_edge ! Left edge value [A]
+  real :: hl, hc ! Left and central cell thicknesses [H]
 
   ! Avoid division by zero for vanished cells
   hl = h_l + h_neglect
@@ -185,24 +189,26 @@ end function PLM_extrapolate_slope
 !! defining 'grid' and 'ppoly'. No consistency check is performed here.
 subroutine PLM_reconstruction( N, h, u, edge_values, ppoly_coef, h_neglect )
   integer,              intent(in)    :: N !< Number of cells
-  real, dimension(:),   intent(in)    :: h !< cell widths (size N)
-  real, dimension(:),   intent(in)    :: u !< cell averages (size N)
+  real, dimension(:),   intent(in)    :: h !< cell widths (size N) [H]
+  real, dimension(:),   intent(in)    :: u !< cell averages (size N) in arbitrary units [A]
   real, dimension(:,:), intent(inout) :: edge_values !< edge values of piecewise polynomials,
-                                           !! with the same units as u.
+                                           !! with the same units as u [A].
   real, dimension(:,:), intent(inout) :: ppoly_coef !< coefficients of piecewise polynomials, mainly
-                                           !! with the same units as u.
+                                           !! with the same units as u [A].
   real,       optional, intent(in)    :: h_neglect !< A negligibly small width for
                                            !! the purpose of cell reconstructions
-                                           !! in the same units as h
+                                           !! in the same units as h [H]
 
   ! Local variables
-  integer       :: k                    ! loop index
-  real          :: u_l, u_r             ! left and right cell averages
-  real          :: slope                ! retained PLM slope
-  real          :: e_r, edge
-  real          :: almost_one
-  real, dimension(N) :: slp, mslp
-  real    :: hNeglect
+  integer       :: k           ! loop index
+  real          :: u_l, u_r    ! left and right cell averages [A]
+  real          :: slope       ! retained PLM slope for a normalized cell width [A]
+  real          :: e_r         ! The edge value in the neighboring cell [A]
+  real          :: edge        ! The projected edge value in the cell [A]
+  real          :: almost_one  ! A value that is slightly smaller than 1 [nondim]
+  real, dimension(N) :: slp    ! The first guess at the normalized tracer slopes [A]
+  real, dimension(N) :: mslp   ! The monotonized normalized tracer slopes [A]
+  real    :: hNeglect          ! A negligibly small width used in cell reconstructions [H]
 
   hNeglect = hNeglect_dflt ; if (present(h_neglect)) hNeglect = h_neglect
 
@@ -265,18 +271,18 @@ end subroutine PLM_reconstruction
 !! defining 'grid' and 'ppoly'. No consistency check is performed here.
 subroutine PLM_boundary_extrapolation( N, h, u, edge_values, ppoly_coef, h_neglect )
   integer,              intent(in)    :: N !< Number of cells
-  real, dimension(:),   intent(in)    :: h !< cell widths (size N)
-  real, dimension(:),   intent(in)    :: u !< cell averages (size N)
+  real, dimension(:),   intent(in)    :: h !< cell widths (size N) [H]
+  real, dimension(:),   intent(in)    :: u !< cell averages (size N) in arbitrary units [A]
   real, dimension(:,:), intent(inout) :: edge_values !< edge values of piecewise polynomials,
-                                           !! with the same units as u.
+                                           !! with the same units as u [A].
   real, dimension(:,:), intent(inout) :: ppoly_coef !< coefficients of piecewise polynomials, mainly
-                                           !! with the same units as u.
+                                           !! with the same units as u [A].
   real,       optional, intent(in)    :: h_neglect !< A negligibly small width for
                                            !! the purpose of cell reconstructions
-                                           !! in the same units as h
+                                           !! in the same units as h [H]
   ! Local variables
-  real    :: slope                ! retained PLM slope
-  real    :: hNeglect
+  real    :: slope     ! retained PLM slope for a normalized cell width [A]
+  real    :: hNeglect  ! A negligibly small width used in cell reconstructions [H]
 
   hNeglect = hNeglect_dflt ; if (present(h_neglect)) hNeglect = h_neglect