Describe the units of 33 real function results

  Added a description of the units of the return values to the comments
describing 33 real functions in 8 modules.  Only comments are changed and all
answers are bitwise identical.

Author: Hallberg-NOAA

src/core/MOM_open_boundary.F90

@@ -1123,7 +1123,7 @@ subroutine initialize_segment_data(G, GV, US, OBC, PF)
 end subroutine initialize_segment_data
 
 !> Return an appropriate dimensional scaling factor for input data based on an OBC segment data
-!! name, or 1 for tracers or other fields that do not match one of the specified names.
+!! name [various ~> 1], or 1 for tracers or other fields that do not match one of the specified names.
 !! Note that calls to register_segment_tracer can come before or after calls to scale_factor_from_name.
 
 real function scale_factor_from_name(name, GV, US, Tr_Reg)

src/parameterizations/lateral/MOM_MEKE.F90

@@ -1995,7 +1995,8 @@ subroutine predict_MEKE(G, US, CS, npts, Time, features_array, MEKE)
 
 end subroutine predict_MEKE
 
-!> Compute average of interface quantities weighted by the thickness of the surrounding layers
+!> Compute average of interface quantities weighted by the thickness of the surrounding
+!! layers [arbitrary]
 real function vertical_average_interface(h, w, h_min)
 
   real, dimension(:), intent(in) :: h  !< Layer Thicknesses [H ~> m or kg m-2]

src/tracer/MOM_hor_bnd_diffusion.F90

@@ -416,7 +416,7 @@ subroutine hbd_grid(boundary, G, GV, hbl, h, CS)
 
 end subroutine hbd_grid
 
-!> Calculate the harmonic mean of two quantities
+!> Calculate the harmonic mean of two quantities [arbitrary]
 !! See \ref section_harmonic_mean.
 real function harmonic_mean(h1,h2)
   real :: h1 !< Scalar quantity [arbitrary]

src/tracer/MOM_neutral_diffusion.F90

@@ -1131,6 +1131,7 @@ end subroutine interface_scalar
 
 !> Returns the PPM quasi-fourth order edge value at k+1/2 following
 !! equation 1.6 in Colella & Woodward, 1984: JCP 54, 174-201.
+!! The returned units are the same as those of Ak (e.g. [C ~> degC] for temperature).
 real function ppm_edge(hkm1, hk, hkp1, hkp2,  Ak, Akp1, Pk, Pkp1, h_neglect)
   real, intent(in) :: hkm1 !< Width of cell k-1 in [H ~> m or kg m-2] or other units
   real, intent(in) :: hk   !< Width of cell k in [H ~> m or kg m-2] or other units
@@ -1289,9 +1290,9 @@ subroutine PLM_diff(nk, h, S, c_method, b_method, diff)
 
 end subroutine PLM_diff
 
-!> Returns the cell-centered second-order finite volume (unlimited PLM) slope
-!! using three consecutive cell widths and average values. Slope is returned
-!! as a difference across the central cell (i.e. units of scalar S).
+!> Returns the cell-centered second-order finite volume (unlimited PLM) slope using three
+!! consecutive cell widths and average values. Slope is returned as a difference across
+!! the central cell (i.e. units of scalar S, e.g. [C ~> degC] for temperature).
 !! Discretization follows equation 1.7 in Colella & Woodward, 1984: JCP 54, 174-201.
 real function fv_diff(hkm1, hk, hkp1, Skm1, Sk, Skp1)
   real, intent(in) :: hkm1 !< Left cell width [H ~> m or kg m-2] or other arbitrary units
@@ -1572,7 +1573,7 @@ subroutine find_neutral_surface_positions_continuous(nk, Pl, Tl, Sl, dRdTl, dRdS
 end subroutine find_neutral_surface_positions_continuous
 
 !> Returns the non-dimensional position between Pneg and Ppos where the
-!! interpolated density difference equals zero.
+!! interpolated density difference equals zero [nondim].
 !! The result is always bounded to be between 0 and 1.
 real function interpolate_for_nondim_position(dRhoNeg, Pneg, dRhoPos, Ppos)
   real, intent(in) :: dRhoNeg !< Negative density difference [R ~> kg m-3]
@@ -1875,7 +1876,8 @@ subroutine mark_unstable_cells(CS, nk, T, S, P, stable_cell)
   enddo
 end subroutine mark_unstable_cells
 
-!> Searches the "other" (searched) column for the position of the neutral surface
+!> Searches the "other" (searched) column for the position of the neutral surface, returning
+!! the fractional postion within the layer [nondim]
 real function search_other_column(CS, ksurf, pos_last, T_from, S_from, P_from, T_top, S_top, P_top, &
                                   T_bot, S_bot, P_bot, T_poly, S_poly ) result(pos)
   type(neutral_diffusion_CS), intent(in   ) :: CS       !< Neutral diffusion control structure

src/tracer/nw2_tracers.F90

@@ -270,7 +270,7 @@ subroutine nw2_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, G, GV, US
 
 end subroutine nw2_tracer_column_physics
 
-!> The target value of a NeverWorld2 tracer label m at non-dimensional
+!> The target value of a NeverWorld2 tracer label m [conc] at non-dimensional
 !! position x=lon/Lx, y=lat/Ly, z=eta/H
 real function nw2_tracer_dist(m, G, GV, eta, i, j, k)
   integer, intent(in) :: m !< Indicates the NW2 tracer

src/user/MOM_wave_interface.F90

@@ -1033,7 +1033,7 @@ subroutine Update_Stokes_Drift(G, GV, US, CS, dz, ustar, dt, dynamics_step)
 
 end subroutine Update_Stokes_Drift
 
-!> Return the value of (1 - exp(-x))/x, using an accurate expression for small values of x.
+!> Return the value of (1 - exp(-x))/x [nondim], using an accurate expression for small values of x.
 real function one_minus_exp_x(x)
   real, intent(in) :: x !< The argument of the function ((1 - exp(-x))/x) [nondim]
   real, parameter :: C1_6 = 1.0/6.0  ! A rational fraction [nondim]
@@ -1045,7 +1045,7 @@ real function one_minus_exp_x(x)
   endif
 end function one_minus_exp_x
 
-!> Return the value of (1 - exp(-x)), using an accurate expression for small values of x.
+!> Return the value of (1 - exp(-x)) [nondim], using an accurate expression for small values of x.
 real function one_minus_exp(x)
   real, intent(in) :: x !< The argument of the function ((1 - exp(-x))/x) [nondim]
   real, parameter :: C1_6 = 1.0/6.0  ! A rational fraction [nondim]

src/user/Neverworld_initialization.F90

@@ -82,7 +82,7 @@ subroutine Neverworld_initialize_topography(D, G, param_file, max_depth)
 
 end subroutine Neverworld_initialize_topography
 
-!> Returns the value of a cosine-bell function evaluated at x/L
+!> Returns the value of a cosine-bell function evaluated at x/L [nondim]
 real function cosbell(x, L)
   real , intent(in) :: x       !< Position in arbitrary units [A]
   real , intent(in) :: L       !< Width in arbitrary units [A]
@@ -92,7 +92,7 @@ real function cosbell(x, L)
   cosbell = 0.5 * (1 + cos(PI*MIN(ABS(x/L),1.0)))
 end function cosbell
 
-!> Returns the value of a sin-spike function evaluated at x/L
+!> Returns the value of a sin-spike function evaluated at x/L [nondim]
 real function spike(x, L)
 
   real , intent(in) :: x       !< Position in arbitrary units [A]
@@ -104,7 +104,7 @@ real function spike(x, L)
 end function spike
 
 !> Returns the value of a triangular function centered at x=x0 with value 1
-!! and linearly decreasing to 0 at x=x0+/-L, and 0 otherwise.
+!! and linearly decreasing to 0 at x=x0+/-L, and 0 otherwise [nondim].
 !! If clip is present the top of the cone is cut off at "clip", which
 !! effectively defaults to 1.
 real function cone(x, x0, L, clip)
@@ -117,7 +117,7 @@ real function cone(x, x0, L, clip)
   if (present(clip)) cone = min(clip, cone)
 end function cone
 
-!> Returns an s-curve s(x) s.t. s(x0)<=0, s(x0+L)>=1 and cubic in between.
+!> Returns an s-curve s(x) s.t. s(x0)<=0, s(x0+L)>=1 and cubic in between [nondim].
 real function scurve(x, x0, L)
   real, intent(in) :: x       !< Coordinate in arbitrary units [A]
   real, intent(in) :: x0      !< position of peak in arbitrary units [A]
@@ -130,7 +130,7 @@ end function scurve
 
 ! None of the following 7 functions appear to be used.
 
-!> Returns a "coastal" profile.
+!> Returns a "coastal" profile [nondim].
 real function cstprof(x, x0, L, lf, bf, sf, sh)
   real, intent(in) :: x       !< Coordinate in arbitrary units [A]
   real, intent(in) :: x0      !< position of peak in arbitrary units [A]
@@ -145,7 +145,7 @@ real function cstprof(x, x0, L, lf, bf, sf, sh)
   cstprof = sh * scurve(s-lf,0.,bf) + (1.-sh) * scurve(s - (1.-sf),0.,sf)
 end function cstprof
 
-!> Distance between points x,y and a line segment (x0,y0) and (x0,y1).
+!> Distance between points x,y and a line segment (x0,y0) and (x0,y1) in arbitrary units [A].
 real function dist_line_fixed_x(x, y, x0, y0, y1)
   real, intent(in) :: x       !< X-coordinate in arbitrary units [A]
   real, intent(in) :: y       !< Y-coordinate in arbitrary units [A]
@@ -160,7 +160,7 @@ real function dist_line_fixed_x(x, y, x0, y0, y1)
   dist_line_fixed_x = sqrt( (dx*dx) + (dy*dy) )
 end function dist_line_fixed_x
 
-!> Distance between points x,y and a line segment (x0,y0) and (x1,y0).
+!> Distance between points x,y and a line segment (x0,y0) and (x1,y0) in arbitrary units [A].
 real function dist_line_fixed_y(x, y, x0, x1, y0)
   real, intent(in) :: x       !< X-coordinate in arbitrary units [A]
   real, intent(in) :: y       !< Y-coordinate in arbitrary units [A]
@@ -171,7 +171,7 @@ real function dist_line_fixed_y(x, y, x0, x1, y0)
   dist_line_fixed_y = dist_line_fixed_x(y, x, y0, x0, x1)
 end function dist_line_fixed_y
 
-!> A "coast profile" applied in an N-S line from lon0,lat0 to lon0,lat1.
+!> A "coast profile" applied in an N-S line from lon0,lat0 to lon0,lat1 [nondim].
 real function NS_coast(lon, lat, lon0, lat0, lat1, dlon, sh)
   real, intent(in) :: lon     !< Longitude [degrees_E]
   real, intent(in) :: lat     !< Latitude [degrees_N]
@@ -186,7 +186,7 @@ real function NS_coast(lon, lat, lon0, lat0, lat1, dlon, sh)
   NS_coast = cstprof(r, 0., dlon, 0.125, 0.125, 0.5, sh)
 end function NS_coast
 
-!> A "coast profile" applied in an E-W line from lon0,lat0 to lon1,lat0.
+!> A "coast profile" applied in an E-W line from lon0,lat0 to lon1,lat0 [nondim].
 real function EW_coast(lon, lat, lon0, lon1, lat0, dlat, sh)
   real, intent(in) :: lon     !< Longitude [degrees_E]
   real, intent(in) :: lat     !< Latitude [degrees_N]
@@ -201,7 +201,7 @@ real function EW_coast(lon, lat, lon0, lon1, lat0, dlat, sh)
   EW_coast = cstprof(r, 0., dlat, 0.125, 0.125, 0.5, sh)
 end function EW_coast
 
-!> A NS ridge
+!> A NS ridge [nondim]
 real function NS_ridge(lon, lat, lon0, lat0, lat1, dlon, rh)
   real, intent(in) :: lon     !< Longitude [degrees_E]
   real, intent(in) :: lat     !< Latitude [degrees_N]
@@ -217,7 +217,7 @@ real function NS_ridge(lon, lat, lon0, lat0, lat1, dlon, rh)
 end function NS_ridge
 
 
-!> A circular ridge
+!> A circular ridge [nondim]
 real function circ_ridge(lon, lat, lon0, lat0, ring_radius, ring_thickness, ridge_height)
   real, intent(in) :: lon            !< Longitude [degrees_E]
   real, intent(in) :: lat            !< Latitude [degrees_N]

src/user/basin_builder.F90

@@ -157,7 +157,7 @@ subroutine basin_builder_topography(D, G, param_file, max_depth)
 end subroutine basin_builder_topography
 
 !> Returns the value of a triangular function centered at x=x0 with value 1
-!! and linearly decreasing to 0 at x=x0+/-L, and 0 otherwise.
+!! and linearly decreasing to 0 at x=x0+/-L, and 0 otherwise [nondim].
 !! If clip is present the top of the cone is cut off at "clip", which
 !! effectively defaults to 1.
 real function cone(x, x0, L, clip)
@@ -170,7 +170,7 @@ real function cone(x, x0, L, clip)
   if (present(clip)) cone = min(clip, cone)
 end function cone
 
-!> Returns an s-curve s(x) s.t. s(x0)<=0, s(x0+L)>=1 and cubic in between.
+!> Returns an s-curve s(x) s.t. s(x0)<=0, s(x0+L)>=1 and cubic in between [nondim].
 real function scurve(x, x0, L)
   real, intent(in) :: x       !< Coordinate in arbitrary units [A]
   real, intent(in) :: x0      !< position of peak in arbitrary units [A]
@@ -181,7 +181,7 @@ real function scurve(x, x0, L)
   scurve = ( 3. - 2.*s ) * ( s * s )
 end function scurve
 
-!> Returns a "coastal" profile.
+!> Returns a "coastal" profile [nondim].
 real function cstprof(x, x0, L, lf, bf, sf, sh)
   real, intent(in) :: x       !< Coordinate in arbitrary units [A]
   real, intent(in) :: x0      !< position of peak in arbitrary units [A]
@@ -196,7 +196,7 @@ real function cstprof(x, x0, L, lf, bf, sf, sh)
   cstprof = sh * scurve(s-lf,0.,bf) + (1.-sh) * scurve(s - (1.-sf),0.,sf)
 end function cstprof
 
-!> Distance between points x,y and a line segment (x0,y0) and (x0,y1).
+!> Distance between points x,y and a line segment (x0,y0) and (x0,y1) in arbitrary units [A].
 real function dist_line_fixed_x(x, y, x0, y0, y1)
   real, intent(in) :: x       !< X-coordinate in arbitrary units [A]
   real, intent(in) :: y       !< Y-coordinate in arbitrary units [A]
@@ -211,7 +211,7 @@ real function dist_line_fixed_x(x, y, x0, y0, y1)
   dist_line_fixed_x = sqrt( (dx*dx) + (dy*dy) )
 end function dist_line_fixed_x
 
-!> Distance between points x,y and a line segment (x0,y0) and (x1,y0).
+!> Distance between points x,y and a line segment (x0,y0) and (x1,y0) in arbitrary units [A].
 real function dist_line_fixed_y(x, y, x0, x1, y0)
   real, intent(in) :: x       !< X-coordinate in arbitrary units [A]
   real, intent(in) :: y       !< Y-coordinate in arbitrary units [A]
@@ -222,7 +222,7 @@ real function dist_line_fixed_y(x, y, x0, x1, y0)
   dist_line_fixed_y = dist_line_fixed_x(y, x, y0, x0, x1)
 end function dist_line_fixed_y
 
-!> An "angled coast profile".
+!> An "angled coast profile" [nondim].
 real function angled_coast(lon, lat, lon_eq, lat_mer, dr, sh)
   real, intent(in) :: lon     !< Longitude [degrees_E]
   real, intent(in) :: lat     !< Latitude [degrees_N]
@@ -238,7 +238,7 @@ real function angled_coast(lon, lat, lon_eq, lat_mer, dr, sh)
   angled_coast = cstprof(r, 0., dr, 0.125, 0.125, 0.5, sh)
 end function angled_coast
 
-!> A "coast profile" applied in an N-S line from lonC,lat0 to lonC,lat1.
+!> A "coast profile" applied in an N-S line from lonC,lat0 to lonC,lat1 [nondim].
 real function NS_coast(lon, lat, lonC, lat0, lat1, dlon, sh)
   real, intent(in) :: lon     !< Longitude [degrees_E]
   real, intent(in) :: lat     !< Latitude [degrees_N]
@@ -253,7 +253,7 @@ real function NS_coast(lon, lat, lonC, lat0, lat1, dlon, sh)
   NS_coast = cstprof(r, 0., dlon, 0.125, 0.125, 0.5, sh)
 end function NS_coast
 
-!> A "coast profile" applied in an E-W line from lon0,latC to lon1,latC.
+!> A "coast profile" applied in an E-W line from lon0,latC to lon1,latC [nondim].
 real function EW_coast(lon, lat, latC, lon0, lon1, dlat, sh)
   real, intent(in) :: lon     !< Longitude [degrees_E]
   real, intent(in) :: lat     !< Latitude [degrees_N]
@@ -268,7 +268,7 @@ real function EW_coast(lon, lat, latC, lon0, lon1, dlat, sh)
   EW_coast = cstprof(r, 0., dlat, 0.125, 0.125, 0.5, sh)
 end function EW_coast
 
-!> A NS ridge with a cone profile
+!> A NS ridge with a cone profile [nondim]
 real function NS_conic_ridge(lon, lat, lonC, lat0, lat1, dlon, rh)
   real, intent(in) :: lon     !< Longitude [degrees_E]
   real, intent(in) :: lat     !< Latitude [degrees_N]
@@ -283,7 +283,7 @@ real function NS_conic_ridge(lon, lat, lonC, lat0, lat1, dlon, rh)
   NS_conic_ridge = 1. - rh * cone(r, 0., dlon)
 end function NS_conic_ridge
 
-!> A NS ridge with an scurve profile
+!> A NS ridge with an scurve profile [nondim]
 real function NS_scurve_ridge(lon, lat, lonC, lat0, lat1, dlon, rh)
   real, intent(in) :: lon     !< Longitude [degrees_E]
   real, intent(in) :: lat     !< Latitude [degrees_N]
@@ -298,7 +298,7 @@ real function NS_scurve_ridge(lon, lat, lonC, lat0, lat1, dlon, rh)
   NS_scurve_ridge = 1. - rh * (1. - scurve(r, 0., dlon) )
 end function NS_scurve_ridge
 
-!> A circular ridge with cutoff conic profile
+!> A circular ridge with cutoff conic profile [nondim]
 real function circ_conic_ridge(lon, lat, lon0, lat0, ring_radius, ring_thickness, ridge_height)
   real, intent(in) :: lon            !< Longitude [degrees_E]
   real, intent(in) :: lat            !< Latitude [degrees_N]
@@ -316,7 +316,7 @@ real function circ_conic_ridge(lon, lat, lon0, lat0, ring_radius, ring_thickness
   circ_conic_ridge = 1. - frac_ht ! nondim depths (1-frac_ridge_height) .. 1
 end function circ_conic_ridge
 
-!> A circular ridge with cutoff scurve profile
+!> A circular ridge with cutoff scurve profile [nondim]
 real function circ_scurve_ridge(lon, lat, lon0, lat0, ring_radius, ring_thickness, ridge_height)
   real, intent(in) :: lon            !< Longitude [degrees_E]
   real, intent(in) :: lat            !< Latitude [degrees_N]