Documented density variable units

  Changed comments to use the square bracket notation to document the units of
about 500 density and related variables.  Also eliminated several redundant
argument documentation blocks.  Only comments have been changed and all answers
are bitwise identical.

config_src/coupled_driver/MOM_surface_forcing.F90

@@ -228,7 +228,7 @@ subroutine convert_IOB_to_fluxes(IOB, fluxes, index_bounds, Time, G, US, CS, sfc
     net_FW,        & ! The area integrated net freshwater flux into the ocean [kg s-1]
     net_FW2,       & ! The area integrated net freshwater flux into the ocean [kg s-1]
     work_sum,      & ! A 2-d array that is used as the work space for global sums [m2] or [kg s-1]
-    open_ocn_mask    ! a binary field indicating where ice is present based on frazil criteria
+    open_ocn_mask    ! a binary field indicating where ice is present based on frazil criteria [nondim]
 
   integer :: i, j, is, ie, js, je, Isq, Ieq, Jsq, Jeq, i0, j0
   integer :: isd, ied, jsd, jed, IsdB, IedB, JsdB, JedB, isr, ier, jsr, jer
@@ -1019,7 +1019,7 @@ subroutine apply_flux_adjustments(G, CS, Time, fluxes)
   type(forcing),            intent(inout) :: fluxes !< Surface fluxes structure
 
   ! Local variables
-  real, dimension(SZI_(G),SZJ_(G)) :: temp_at_h ! Fluxes at h points (W m-2 or kg m-2 s-1)
+  real, dimension(SZI_(G),SZJ_(G)) :: temp_at_h ! Various fluxes at h points [W m-2] or [kg m-2 s-1]
 
   integer :: isc, iec, jsc, jec, i, j
   logical :: overrode_h

config_src/coupled_driver/ocean_model_MOM.F90

@@ -239,7 +239,7 @@ subroutine ocean_model_init(Ocean_sfc, OS, Time_init, Time_in, gas_fields_ocn)
                                               !! tracer fluxes, and can be used to spawn related
                                               !! internal variables in the ice model.
   ! Local variables
-  real :: Rho0        ! The Boussinesq ocean density, in kg m-3.
+  real :: Rho0        ! The Boussinesq ocean density [kg m-3].
   real :: G_Earth     ! The gravitational acceleration [m s-2].
   real :: HFrz        !< If HFrz > 0 (m), melt potential will be computed.
                       !! The actual depth over which melt potential is computed will

config_src/ice_solo_driver/user_surface_forcing.F90

@@ -79,7 +79,7 @@ module user_surface_forcing
                              ! state variables.
   logical :: restorebuoy     ! If true, use restoring surface buoyancy forcing.
   real :: Rho0               !   The density used in the Boussinesq
-                             ! approximation, in kg m-3.
+                             ! approximation [kg m-3].
   real :: G_Earth            !   The gravitational acceleration [m s-2].
   real :: Flux_const         !   The restoring rate at the surface [m s-1].
   real :: gust_const         !   A constant unresolved background gustiness
@@ -109,15 +109,6 @@ subroutine USER_wind_forcing(sfc_state, forces, day, G, US, CS)
 ! direction as the u- and v- velocities.)  They are both in Pa.
 !   In addition, this subroutine can be used to set the surface friction
 ! velocity, forces%ustar [Z s-1 ~> m s-1]. This is needed with a bulk mixed layer.
-!
-! Arguments: state - A structure containing fields that describe the
-!                    surface state of the ocean.
-!  (out)     fluxes - A structure containing pointers to any possible
-!                     forcing fields.  Unused fields have NULL ptrs.
-!  (in)      day - Time of the fluxes.
-!  (in)      G - The ocean's grid structure.
-!  (in)      CS - A pointer to the control structure returned by a previous
-!                 call to user_surface_forcing_init
 
   integer :: i, j, is, ie, js, je, Isq, Ieq, Jsq, Jeq
   integer :: isd, ied, jsd, jed, IsdB, IedB, JsdB, JedB
@@ -186,24 +177,13 @@ subroutine USER_buoyancy_forcing(sfc_state, fluxes, day, dt, G, CS)
 !  are in W m-2 and positive for heat going into the ocean.  All fresh water
 !  fluxes are in kg m-2 s-1 and positive for water moving into the ocean.
 
-! Arguments: state - A structure containing fields that describe the
-!                    surface state of the ocean.
-!  (out)     fluxes - A structure containing pointers to any possible
-!                     forcing fields.  Unused fields have NULL ptrs.
-!  (in)      day_start - Start time of the fluxes.
-!  (in)      day_interval - Length of time over which these fluxes
-!                           will be applied.
-!  (in)      G - The ocean's grid structure.
-!  (in)      CS - A pointer to the control structure returned by a previous
-!                 call to user_surface_forcing_init
-
   real :: Temp_restore   ! The temperature that is being restored toward, in C.
   real :: Salin_restore  ! The salinity that is being restored toward, in PSU.
   real :: density_restore  ! The potential density that is being restored
-                         ! toward, in kg m-3.
-  real :: rhoXcp ! The mean density times the heat capacity, in J m-3 K-1.
+                         ! toward [kg m-3].
+  real :: rhoXcp ! The mean density times the heat capacity [J m-3 degC-1].
   real :: buoy_rest_const  ! A constant relating density anomalies to the
-                           ! restoring buoyancy flux, in m5 s-3 kg-1.
+                           ! restoring buoyancy flux [m5 s-3 kg-1].
 
   integer :: i, j, is, ie, js, je
   integer :: isd, ied, jsd, jed
@@ -294,7 +274,7 @@ subroutine USER_buoyancy_forcing(sfc_state, fluxes, day, dt, G, CS)
       buoy_rest_const = -1.0 * (CS%G_Earth * CS%Flux_const) / CS%Rho0
       do j=js,je ; do i=is,ie
        !   Set density_restore to an expression for the surface potential
-       ! density in kg m-3 that is being restored toward.
+       ! density [kg m-3] that is being restored toward.
         density_restore = 1030.0
 
         fluxes%buoy(i,j) = G%mask2dT(i,j) * buoy_rest_const * &
@@ -314,16 +294,8 @@ subroutine USER_surface_forcing_init(Time, G, param_file, diag, CS)
   type(user_surface_forcing_CS), pointer    :: CS   !< A pointer that is set to point to
                                                     !! the control structure for this module
 
-! Arguments: Time - The current model time.
-!  (in)      G - The ocean's grid structure.
-!  (in)      param_file - A structure indicating the open file to parse for
-!                         model parameter values.
-!  (in)      diag - A structure that is used to regulate diagnostic output.
-!  (in/out)  CS - A pointer that is set to point to the control structure
-!                 for this module
-
-! 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 = "user_surface_forcing" ! This module's name.
 
   if (associated(CS)) then

config_src/mct_driver/MOM_ocean_model.F90

@@ -247,7 +247,7 @@ subroutine ocean_model_init(Ocean_sfc, OS, Time_init, Time_in, gas_fields_ocn, i
 ! Because of the way that indicies and domains are handled, Ocean_sfc must have
 ! been used in a previous call to initialize_ocean_type.
 
-  real :: Rho0           !< The Boussinesq ocean density, in kg m-3.
+  real :: Rho0           !< The Boussinesq ocean density [kg m-3].
   real :: G_Earth        !< The gravitational acceleration [m s-2].
                          !! This include declares and sets the variable "version".
   real :: HFrz           !< If HFrz > 0 (m), melt potential will be computed.

config_src/solo_driver/MESO_surface_forcing.F90

@@ -26,7 +26,7 @@ module MESO_surface_forcing
 
   logical :: use_temperature !< If true, temperature and salinity are used as state variables.
   logical :: restorebuoy     !< If true, use restoring surface buoyancy forcing.
-  real :: Rho0               !< The density used in the Boussinesq approximation, in kg m-3.
+  real :: Rho0               !< The density used in the Boussinesq approximation [kg m-3].
   real :: G_Earth            !< The gravitational acceleration [m s-2].
   real :: Flux_const         !< The restoring rate at the surface [m s-1].
   real :: gust_const         !< A constant unresolved background gustiness
@@ -75,13 +75,13 @@ subroutine MESO_buoyancy_forcing(sfc_state, fluxes, day, dt, G, CS)
 !  are in W m-2 and positive for heat going into the ocean.  All fresh water
 !  fluxes are in kg m-2 s-1 and positive for water moving into the ocean.
 
-  real :: Temp_restore   ! The temperature that is being restored toward, in C.
+  real :: Temp_restore   ! The temperature that is being restored toward [degC].
   real :: Salin_restore  ! The salinity that is being restored toward, in PSU.
   real :: density_restore  ! The potential density that is being restored
-                         ! toward, in kg m-3.
-  real :: rhoXcp ! The mean density times the heat capacity, in J m-3 K-1.
+                         ! toward [kg m-3].
+  real :: rhoXcp ! The mean density times the heat capacity [J m-3 degC-1].
   real :: buoy_rest_const  ! A constant relating density anomalies to the
-                           ! restoring buoyancy flux, in m5 s-3 kg-1.
+                           ! restoring buoyancy flux [m5 s-3 kg-1].
 
   integer :: i, j, is, ie, js, je
   integer :: isd, ied, jsd, jed
@@ -192,7 +192,7 @@ subroutine MESO_buoyancy_forcing(sfc_state, fluxes, day, dt, G, CS)
       buoy_rest_const = -1.0 * (CS%G_Earth * CS%Flux_const) / CS%Rho0
       do j=js,je ; do i=is,ie
        !   Set density_restore to an expression for the surface potential
-       ! density in kg m-3 that is being restored toward.
+       ! density [kg m-3] that is being restored toward.
         density_restore = 1030.0
 
         fluxes%buoy(i,j) = G%mask2dT(i,j) * buoy_rest_const * &

config_src/solo_driver/Neverland_surface_forcing.F90

@@ -32,7 +32,7 @@ module Neverland_surface_forcing
   logical :: use_temperature !< If true, use temperature and salinity.
   logical :: restorebuoy     !< If true, use restoring surface buoyancy forcing.
   real :: Rho0               !< The density used in the Boussinesq
-                             !! approximation, in kg m-3.
+                             !! approximation [kg m-3].
   real :: G_Earth            !< The gravitational acceleration [m s-2].
   real :: flux_const         !<  The restoring rate at the surface [m s-1].
   real, dimension(:,:), pointer :: &
@@ -197,7 +197,7 @@ subroutine Neverland_buoyancy_forcing(sfc_state, fluxes, day, dt, G, CS)
       buoy_rest_const = -1.0 * (CS%G_Earth * CS%flux_const) / CS%Rho0
       do j=js,je ; do i=is,ie
        !   Set density_restore to an expression for the surface potential
-       ! density in kg m-3 that is being restored toward.
+       ! density [kg m-3] that is being restored toward.
         density_restore = 1030.0
 
         fluxes%buoy(i,j) = G%mask2dT(i,j) * buoy_rest_const * &

config_src/solo_driver/user_surface_forcing.F90

@@ -33,7 +33,7 @@ module user_surface_forcing
 
   logical :: use_temperature !< If true, temperature and salinity are used as state variables.
   logical :: restorebuoy     !< If true, use restoring surface buoyancy forcing.
-  real :: Rho0               !< The density used in the Boussinesq approximation, in kg m-3.
+  real :: Rho0               !< The density used in the Boussinesq approximation [kg m-3].
   real :: G_Earth            !< The gravitational acceleration [m s-2].
   real :: Flux_const         !< The restoring rate at the surface [m s-1].
   real :: gust_const         !< A constant unresolved background gustiness
@@ -124,13 +124,13 @@ subroutine USER_buoyancy_forcing(sfc_state, fluxes, day, dt, G, CS)
 !  fluxes are in kg m-2 s-1 and positive for water moving into the ocean.
 
   ! Local variables
-  real :: Temp_restore   ! The temperature that is being restored toward, in C.
+  real :: Temp_restore   ! The temperature that is being restored toward [degC].
   real :: Salin_restore  ! The salinity that is being restored toward, in PSU.
   real :: density_restore  ! The potential density that is being restored
-                         ! toward, in kg m-3.
-  real :: rhoXcp         ! The mean density times the heat capacity, in J m-3 K-1.
+                         ! toward [kg m-3].
+  real :: rhoXcp         ! The mean density times the heat capacity [J m-3 degC-1].
   real :: buoy_rest_const  ! A constant relating density anomalies to the
-                           ! restoring buoyancy flux, in m5 s-3 kg-1.
+                           ! restoring buoyancy flux [m5 s-3 kg-1].
 
   integer :: i, j, is, ie, js, je
   integer :: isd, ied, jsd, jed
@@ -221,7 +221,7 @@ subroutine USER_buoyancy_forcing(sfc_state, fluxes, day, dt, G, CS)
       buoy_rest_const = -1.0 * (CS%G_Earth * CS%Flux_const) / CS%Rho0
       do j=js,je ; do i=is,ie
        !   Set density_restore to an expression for the surface potential
-       ! density in kg m-3 that is being restored toward.
+       ! density [kg m-3] that is being restored toward.
         density_restore = 1030.0
 
         fluxes%buoy(i,j) = G%mask2dT(i,j) * buoy_rest_const * &

src/ALE/coord_rho.F90

@@ -26,7 +26,7 @@ module coord_rho
   !! If false, integrate from the bottom upward, as does the rest of the model.
   logical :: integrate_downward_for_e = .false.
 
-  !> Nominal density of interfaces, in kg m-3
+  !> Nominal density of interfaces [kg m-3]
   real, allocatable, dimension(:) :: target_density
 
   !> Interpolation control structure
@@ -47,7 +47,7 @@ subroutine init_coord_rho(CS, nk, ref_pressure, target_density, interp_CS)
   type(rho_CS),         pointer    :: CS !< Unassociated pointer to hold the control structure
   integer,              intent(in) :: nk !< Number of layers in the grid
   real,                 intent(in) :: ref_pressure !< Nominal density of interfaces in Pa
-  real, dimension(:),   intent(in) :: target_density !< Nominal density of interfaces in kg m-3
+  real, dimension(:),   intent(in) :: target_density !< Nominal density of interfaces [kg m-3]
   type(interp_CS_type), intent(in) :: interp_CS !< Controls for interpolation
 
   if (associated(CS)) call MOM_error(FATAL, "init_coord_rho: CS already associated!")

src/ALE/coord_slight.F90

@@ -51,7 +51,7 @@ module coord_slight
   !> A value of the stratification ratio that defines a problematic halocline region (nondim).
   real :: halocline_strat_tol
 
-  !> Nominal density of interfaces, in kg m-3.
+  !> Nominal density of interfaces [kg m-3].
   real, allocatable, dimension(:) :: target_density
 
   !> Maximum depths of interfaces [H ~> m or kg m-2].
@@ -73,7 +73,7 @@ subroutine init_coord_slight(CS, nk, ref_pressure, target_density, interp_CS, m_
   type(slight_CS),      pointer    :: CS !< Unassociated pointer to hold the control structure
   integer,              intent(in) :: nk !< Number of layers in the grid
   real,                 intent(in) :: ref_pressure !< Nominal density of interfaces in Pa
-  real, dimension(:),   intent(in) :: target_density !< Nominal density of interfaces in kg m-3
+  real, dimension(:),   intent(in) :: target_density !< Nominal density of interfaces [kg m-3]
   type(interp_CS_type), intent(in) :: interp_CS !< Controls for interpolation
   real,       optional, intent(in) :: m_to_H !< A conversion factor from m to the units of thicknesses
 
@@ -211,9 +211,9 @@ subroutine build_slight_column(CS, eqn_of_state, H_to_Pa, H_subroundoff, &
   real :: dz      ! A uniform layer thickness in very shallow water [H ~> m or kg m-2].
   real :: dz_ur   ! The total thickness of an unstable region [H ~> m or kg m-2].
   real :: wgt, cowgt  ! A weight and its complement, nondim.
-  real :: rho_ml_av ! The average potential density in a near-surface region, in kg m-3.
+  real :: rho_ml_av ! The average potential density in a near-surface region [kg m-3].
   real :: H_ml_av ! A thickness to try to use in taking the near-surface average [H ~> m or kg m-2].
-  real :: rho_x_z ! A cumulative integral of a density, in kg m-3 H.
+  real :: rho_x_z ! A cumulative integral of a density [kg m-3 H ~> kg m-2 or kg2 m-5].
   real :: z_wt    ! The thickness actually used in taking the near-surface average [H ~> m or kg m-2].
   real :: k_interior  ! The (real) value of k where the interior grid starts.
   real :: k_int2      ! The (real) value of k where the interior grid starts.
@@ -503,7 +503,7 @@ subroutine rho_interfaces_col(rho_col, h_col, z_col, rho_tgt, nz, z_col_new, &
   real, dimension(nz,DEGREE_MAX+1) :: ppoly_i_coefficients ! Coefficients of polynomial
   logical, dimension(nz)   :: unstable_lay ! If true, this layer is in an unstable region.
   logical, dimension(nz+1) :: unstable_int ! If true, this interface is in an unstable region.
-  real :: rt  ! The current target density, in kg m-3.
+  real :: rt  ! The current target density [kg m-3].
   real :: zf  ! The fractional z-position within a layer of the target density.
   real :: rfn
   real :: a(5) ! Coefficients of a local polynomial minus the target density.

src/ALE/regrid_interp.F90

@@ -298,7 +298,7 @@ end subroutine interpolate_grid
 subroutine build_and_interpolate_grid(CS, densities, n0, h0, x0, target_values, &
                                       n1, h1, x1, h_neglect, h_neglect_edge)
   type(interp_CS_type), intent(in)  :: CS  !< A control structure for regrid_interp
-  real, dimension(:), intent(in)    :: densities !< Input cell densities, in kg m-3
+  real, dimension(:), intent(in)    :: densities !< Input cell densities [kg m-3]
   real, dimension(:), intent(in)    :: target_values !< Target values of interfaces
   integer,            intent(in)    :: n0  !< The number of points on the input grid
   real, dimension(:), intent(in)    :: h0  !< Initial cell widths

src/core/MOM.F90

@@ -1537,11 +1537,10 @@ 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
-  real    :: Z_diag_int  ! minimum interval between calc depth-space diagnostics [s]
+  real    :: dtbt        ! The barotropic timestep [s]
+  real    :: Z_diag_int  ! minimum interval between calc depth-space diagnosetics [s]
 
-  real, allocatable, dimension(:,:,:) :: e   ! interface heights (meter)
-  real, allocatable, dimension(:,:)   :: eta ! free surface height [m] or column mass [kg m-2]
+  real, allocatable, dimension(:,:)   :: eta ! free surface height or column mass [H ~> m or kg m-2]
   real, allocatable, dimension(:,:)   :: area_shelf_h ! area occupied by ice shelf [m2]
   real, dimension(:,:), allocatable, target  :: frac_shelf_h ! fraction of total area occupied by ice shelf [nondim]
   real, dimension(:,:), pointer :: shelf_area => NULL()
@@ -2660,14 +2659,14 @@ subroutine adjust_ssh_for_p_atm(tv, G, GV, US, ssh, p_atm, use_EOS)
   type(ocean_grid_type),             intent(in)    :: G   !< ocean grid structure
   type(verticalGrid_type),           intent(in)    :: GV  !< ocean vertical grid structure
   type(unit_scale_type),             intent(in)    :: US  !< A dimensional unit scaling type
-  real, dimension(SZI_(G),SZJ_(G)),  intent(inout) :: ssh !< time mean surface height (m)
-  real, dimension(:,:),    optional, pointer       :: p_atm !< atmospheric pressure (Pascal)
+  real, dimension(SZI_(G),SZJ_(G)),  intent(inout) :: ssh !< time mean surface height [m]
+  real, dimension(:,:),    optional, pointer       :: p_atm !< atmospheric pressure [Pa]
   logical,                 optional, intent(in)    :: use_EOS !< If true, calculate the density for
                                                        !! the SSH correction using the equation of state.
 
   real :: Rho_conv    ! The density used to convert surface pressure to
-                      ! a corrected effective SSH, in kg m-3.
-  real :: IgR0        ! The SSH conversion factor from Pa to m.
+                      ! a corrected effective SSH [kg m-3].
+  real :: IgR0        ! The SSH conversion factor from Pa to m [m Pa-1].
   logical :: calc_rho
   integer :: i, j, is, ie, js, je