diff --git a/src/equation_of_state/MOM_TFreeze.F90 b/src/equation_of_state/MOM_TFreeze.F90 index 7893b8e759..7f112ac734 100644 --- a/src/equation_of_state/MOM_TFreeze.F90 +++ b/src/equation_of_state/MOM_TFreeze.F90 @@ -66,12 +66,22 @@ subroutine calculate_TFreeze_linear_scalar(S, pres, T_Fr, TFr_S0_P0, & end subroutine calculate_TFreeze_linear_scalar +!> This subroutine computes the freezing point potential temparature +!! (in deg C) from salinity (in psu), and pressure (in Pa) using a simple +!! linear expression, with coefficients passed in as arguments. subroutine calculate_TFreeze_linear_array(S, pres, T_Fr, start, npts, & TFr_S0_P0, dTFr_dS, dTFr_dp) - real, dimension(:), intent(in) :: S, pres - real, dimension(:), intent(out) :: T_Fr - integer, intent(in) :: start, npts - real, intent(in) :: TFr_S0_P0, dTFr_dS, dTFr_dp + real, dimension(:), intent(in) :: S !< salinity in PSU. + real, dimension(:), intent(in) :: pres !< pressure in Pa. + real, dimension(:), intent(out) :: T_Fr !< Freezing point potential temperature in deg C. + integer, intent(in) :: start !< the starting point in the arrays. + integer, intent(in) :: npts !< the number of values to calculate. + real, intent(in) :: TFr_S0_P0 !< The freezing point at S=0, p=0, in deg C. + real, intent(in) :: dTFr_dS !< The derivative of freezing point with salinity, + !! in deg C PSU-1. + real, intent(in) :: dTFr_dp !< The derivative of freezing point with pressure, + !! in deg C Pa-1. + ! This subroutine computes the freezing point potential temparature ! (in deg C) from salinity (in psu), and pressure (in Pa) using a simple ! linear expression, with coefficients passed in as arguments. @@ -94,9 +104,17 @@ subroutine calculate_TFreeze_linear_array(S, pres, T_Fr, start, npts, & end subroutine calculate_TFreeze_linear_array +!> This subroutine computes the freezing point potential temparature +!! (in deg C) from salinity (in psu), and pressure (in Pa) using the expression +!! from Millero (1978) (and in appendix A of Gill 1982), but with the of the +!! pressure dependence changed from 7.53e-8 to 7.75e-8 to make this an +!! expression for potential temperature (not in situ temperature), using a +!! value that is correct at the freezing point at 35 PSU and 5e6 Pa (500 dbar). subroutine calculate_TFreeze_Millero_scalar(S, pres, T_Fr) - real, intent(in) :: S, pres - real, intent(out) :: T_Fr + real, intent(in) :: S !< Salinity in PSU. + real, intent(in) :: pres !< Pressure in Pa. + real, intent(out) :: T_Fr !< Freezing point potential temperature in deg C. + ! This subroutine computes the freezing point potential temparature ! (in deg C) from salinity (in psu), and pressure (in Pa) using the expression ! from Millero (1978) (and in appendix A of Gill 1982), but with the of the @@ -114,11 +132,18 @@ subroutine calculate_TFreeze_Millero_scalar(S, pres, T_Fr) end subroutine calculate_TFreeze_Millero_scalar - +!> This subroutine computes the freezing point potential temparature +!! (in deg C) from salinity (in psu), and pressure (in Pa) using the expression +!! from Millero (1978) (and in appendix A of Gill 1982), but with the of the +!! pressure dependence changed from 7.53e-8 to 7.75e-8 to make this an +!! expression for potential temperature (not in situ temperature), using a +!! value that is correct at the freezing point at 35 PSU and 5e6 Pa (500 dbar). subroutine calculate_TFreeze_Millero_array(S, pres, T_Fr, start, npts) - real, dimension(:), intent(in) :: S, pres - real, dimension(:), intent(out) :: T_Fr - integer, intent(in) :: start, npts + real, dimension(:), intent(in) :: S !< Salinity in PSU. + real, dimension(:), intent(in) :: pres !< Pressure in Pa. + real, dimension(:), intent(out) :: T_Fr !< Freezing point potential temperature in deg C. + integer, intent(in) :: start !< The starting point in the arrays. + integer, intent(in) :: npts !< The number of values to calculate. ! This subroutine computes the freezing point potential temparature ! (in deg C) from salinity (in psu), and pressure (in Pa) using the expression ! from Millero (1978) (and in appendix A of Gill 1982), but with the of the @@ -142,9 +167,13 @@ subroutine calculate_TFreeze_Millero_array(S, pres, T_Fr, start, npts) end subroutine calculate_TFreeze_Millero_array +!> This subroutine computes the freezing point conservative temparature +!! (in deg C) from absolute salinity (in g/kg), and pressure (in Pa) using the +!! TEOS10 package. subroutine calculate_TFreeze_teos10_scalar(S, pres, T_Fr) - real, intent(in) :: S, pres - real, intent(out) :: T_Fr + real, intent(in) :: S !< Absolute salinity in g/kg. + real, intent(in) :: pres !< Pressure in Pa. + real, intent(out) :: T_Fr !< Freezing point conservative temperature in deg C. ! This subroutine computes the freezing point conservative temparature ! (in deg C) from absolute salinity (in g/kg), and pressure (in Pa) using the ! TEOS10 package. @@ -163,10 +192,15 @@ subroutine calculate_TFreeze_teos10_scalar(S, pres, T_Fr) end subroutine calculate_TFreeze_teos10_scalar +!> This subroutine computes the freezing point conservative temparature +!! (in deg C) from absolute salinity (in g/kg), and pressure (in Pa) using the +!! TEOS10 package. subroutine calculate_TFreeze_teos10_array(S, pres, T_Fr, start, npts) - real, dimension(:), intent(in) :: S, pres - real, dimension(:), intent(out) :: T_Fr - integer, intent(in) :: start, npts + real, dimension(:), intent(in) :: S !< absolute salinity in g/kg. + real, dimension(:), intent(in) :: pres !< pressure in Pa. + real, dimension(:), intent(out) :: T_Fr !< Freezing point conservative temperature in deg C. + integer, intent(in) :: start !< the starting point in the arrays. + integer, intent(in) :: npts !< the number of values to calculate. ! This subroutine computes the freezing point conservative temparature ! (in deg C) from absolute salinity (in g/kg), and pressure (in Pa) using the ! TEOS10 package. diff --git a/src/parameterizations/lateral/MOM_hor_visc.F90 b/src/parameterizations/lateral/MOM_hor_visc.F90 index 2ad88948d6..be450c2062 100644 --- a/src/parameterizations/lateral/MOM_hor_visc.F90 +++ b/src/parameterizations/lateral/MOM_hor_visc.F90 @@ -216,18 +216,39 @@ module MOM_hor_visc contains +!> This subroutine determines the acceleration due to the +!! horizontal viscosity. A combination of biharmonic and Laplacian +!! forms can be used. The coefficient may either be a constant or +!! a shear-dependent form. The biharmonic is determined by twice +!! taking the divergence of an appropriately defined stress tensor. +!! The Laplacian is determined by doing so once. +!! To work, the following fields must be set outside of the usual +!! is to ie range before this subroutine is called: +!! v[is-2,is-1,ie+1,ie+2], u[is-2,is-1,ie+1,ie+2], and h[is-1,ie+1], +!! with a similarly sized halo in the y-direction. subroutine horizontal_viscosity(u, v, h, diffu, diffv, MEKE, VarMix, G, GV, CS, OBC) - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure - type(verticalGrid_type), intent(in) :: GV !< The ocean's vertical grid structure - real, dimension(SZIB_(G),SZJ_(G),SZK_(G)), intent(in) :: u !< The zonal velocity, in m s-1 - real, dimension(SZI_(G),SZJB_(G),SZK_(G)), intent(in) :: v !< The meridional velocity, in m s-1 - real, dimension(SZI_(G),SZJ_(G),SZK_(G)), intent(in) :: h !< Layer thicknesses, in H (usually m or kg m-2) - real, dimension(SZIB_(G),SZJ_(G),SZK_(G)), intent(out) :: diffu - real, dimension(SZI_(G),SZJB_(G),SZK_(G)), intent(out) :: diffv - type(MEKE_type), pointer :: MEKE - type(VarMix_CS), pointer :: VarMix - type(hor_visc_CS), pointer :: CS - type(ocean_OBC_type), pointer, optional :: OBC + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. + type(verticalGrid_type), intent(in) :: GV !< The ocean's vertical grid structure. + real, dimension(SZIB_(G),SZJ_(G),SZK_(G)), & + intent(in) :: u !< The zonal velocity, in m s-1. + real, dimension(SZI_(G),SZJB_(G),SZK_(G)), & + intent(in) :: v !< The meridional velocity, in m s-1. + real, dimension(SZI_(G),SZJ_(G),SZK_(G)), & + intent(in) :: h !< Layer thicknesses, in H + !! (usually m or kg m-2). + real, dimension(SZIB_(G),SZJ_(G),SZK_(G)), & + intent(out) :: diffu !< Zonal acceleration due to convergence of + !! along-coordinate stress tensor (m/s2) + real, dimension(SZI_(G),SZJB_(G),SZK_(G)), & + intent(out) :: diffv !< Meridional acceleration due to convergence + !! of along-coordinate stress tensor (m/s2). + type(MEKE_type), pointer :: MEKE !< Pointer to a structure containing fields + !! related to Mesoscale Eddy Kinetic Energy. + type(VarMix_CS), pointer :: VarMix !< Pointer to a structure with fields that + !! specify the spatially variable viscosities + type(hor_visc_CS), pointer :: CS !< Pontrol structure returned by a previous + !! call to hor_visc_init. + type(ocean_OBC_type), pointer, optional :: OBC !< Pointer to an open boundary condition type ! Arguments: ! (in) u - zonal velocity (m/s) @@ -929,13 +950,18 @@ subroutine horizontal_viscosity(u, v, h, diffu, diffv, MEKE, VarMix, G, GV, CS, end subroutine horizontal_viscosity - +!> This subroutine allocates space for and calculates static variables +!! used by this module. The metrics may be 0, 1, or 2-D arrays, +!! while fields like the background viscosities are 2-D arrays. +!! ALLOC is a macro defined in MOM_memory.h to either allocate +!! for dynamic memory, or do nothing when using static memory. subroutine hor_visc_init(Time, G, param_file, diag, CS) - type(time_type), intent(in) :: Time - type(ocean_grid_type), intent(inout) :: G !< The ocean's grid structure - type(param_file_type), intent(in) :: param_file !< A structure to parse for run-time parameters - type(diag_ctrl), target, intent(inout) :: diag - type(hor_visc_CS), pointer :: CS + type(time_type), intent(in) :: Time !< current model time. + type(ocean_grid_type), intent(inout) :: G !< The ocean's grid structure. + type(param_file_type), intent(in) :: param_file !< A structure to parse for run-time + !! parameters. + type(diag_ctrl), target, intent(inout) :: diag !< structure to regulate diagnostic output. + type(hor_visc_CS), pointer :: CS !< pointer to the control structure for this module ! This subroutine allocates space for and calculates static variables ! used by this module. The metrics may be 0, 1, or 2-D arrays, diff --git a/src/parameterizations/lateral/MOM_internal_tides.F90 b/src/parameterizations/lateral/MOM_internal_tides.F90 index 243e97a12e..8325a59efd 100644 --- a/src/parameterizations/lateral/MOM_internal_tides.F90 +++ b/src/parameterizations/lateral/MOM_internal_tides.F90 @@ -197,19 +197,29 @@ module MOM_internal_tides contains - +!> This subroutine calls other subroutines in this file that are needed to +!! refract, propagate, and dissipate energy density of the internal tide. subroutine propagate_int_tide(h, tv, cn, TKE_itidal_input, vel_btTide, Nb, dt, & G, GV, CS) - type(ocean_grid_type), intent(inout) :: G !< The ocean's grid structure - type(verticalGrid_type), intent(in) :: GV !< The ocean's vertical grid structure + type(ocean_grid_type), intent(inout) :: G !< The ocean's grid structure. + type(verticalGrid_type), intent(in) :: GV !< The ocean's vertical grid structure. real, dimension(SZI_(G),SZJ_(G),SZK_(G)), & - intent(in) :: h !< Layer thicknesses, in H (usually m or kg m-2) - type(thermo_var_ptrs), intent(in) :: tv - real, dimension(SZI_(G),SZJ_(G)), intent(in) :: TKE_itidal_input - real, dimension(SZI_(G),SZJ_(G)), intent(in) :: vel_btTide, Nb - real, intent(in) :: dt - type(int_tide_CS), pointer :: CS - real, dimension(SZI_(G),SZJ_(G),CS%nMode), intent(in) :: cn + intent(in) :: h !< Layer thicknesses, in H + !! (usually m or kg m-2). + type(thermo_var_ptrs), intent(in) :: tv !< Pointer to thermodynamic variables + !! (needed for wave structure). + real, dimension(SZI_(G),SZJ_(G)), intent(in) :: TKE_itidal_input !< The energy input to the + !! internal waves, in W m-2. + real, dimension(SZI_(G),SZJ_(G)), intent(in) :: vel_btTide !< Barotropic velocity read + !! from file, in m s-1. + real, dimension(SZI_(G),SZJ_(G)), intent(in) :: Nb !< Near-bottom buoyancy frequency, in s-1. + real, intent(in) :: dt !< Length of time over which these fluxes + !! will be applied, in s. + type(int_tide_CS), pointer :: CS !< A pointer to the control structure + !! returned by a previous call to + !! int_tide_init. + real, dimension(SZI_(G),SZJ_(G),CS%nMode), & + intent(in) :: cn ! This subroutine calls other subroutines in this file that are needed to ! refract, propagate, and dissipate energy density of the internal tide. @@ -645,8 +655,9 @@ subroutine propagate_int_tide(h, tv, cn, TKE_itidal_input, vel_btTide, Nb, dt, & end subroutine propagate_int_tide +!> This subroutine checks for energy conservation on computational domain subroutine sum_En(G, CS, En, label) - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. type(int_tide_CS), pointer :: CS real, dimension(G%isd:G%ied,G%jsd:G%jed,CS%NAngle), intent(in) :: En character(len=*), intent(in) :: label @@ -685,16 +696,27 @@ subroutine sum_En(G, CS, En, label) end subroutine sum_En +!> This subroutine calculates the energy lost from the propagating internal tide due to +!! scattering over small-scale roughness along the lines of Jayne & St. Laurent (2001). subroutine itidal_lowmode_loss(G, CS, Nb, Ub, En, TKE_loss_fixed, TKE_loss, dt, full_halos) - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure - type(int_tide_CS), pointer :: CS - real, dimension(G%isd:G%ied,G%jsd:G%jed), intent(in) :: Nb - real, dimension(G%isd:G%ied,G%jsd:G%jed,CS%nFreq,CS%nMode), intent(inout) :: Ub - real, dimension(G%isd:G%ied,G%jsd:G%jed), intent(in) :: TKE_loss_fixed - real, dimension(G%isd:G%ied,G%jsd:G%jed,CS%NAngle,CS%nFreq,CS%nMode), intent(inout) :: En - real, dimension(G%isd:G%ied,G%jsd:G%jed,CS%NAngle,CS%nFreq,CS%nMode), intent(out) :: TKE_loss - real, intent(in) :: dt - logical,optional, intent(in) :: full_halos + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. + type(int_tide_CS), pointer :: CS + real, dimension(G%isd:G%ied,G%jsd:G%jed), & + intent(in) :: Nb !< Near-bottom stratification, in s-1. + real, dimension(G%isd:G%ied,G%jsd:G%jed,CS%nFreq,CS%nMode), & + intent(inout) :: Ub !< Rms (over one period) near-bottom horizontal + !! mode velocity , in m s-1. + real, dimension(G%isd:G%ied,G%jsd:G%jed), & + intent(in) :: TKE_loss_fixed !< Fixed part of energy loss, + !! in kg m-2 (rho*kappa*h^2). + real, dimension(G%isd:G%ied,G%jsd:G%jed,CS%NAngle,CS%nFreq,CS%nMode), & + intent(inout) :: En !< Energy density of the internal waves, in J m-2. + real, dimension(G%isd:G%ied,G%jsd:G%jed,CS%NAngle,CS%nFreq,CS%nMode), & + intent(out) :: TKE_loss !< Energy loss rate, in W m-2 + !! (q*rho*kappa*h^2*N*U^2). + real, intent(in) :: dt !< Time increment, in s. + logical,optional, intent(in) :: full_halos !< If true, do the calculation over the + !! entirecomputational domain. ! This subroutine calculates the energy lost from the propagating internal tide due to ! scattering over small-scale roughness along the lines of Jayne & St. Laurent (2001). @@ -774,13 +796,17 @@ subroutine itidal_lowmode_loss(G, CS, Nb, Ub, En, TKE_loss_fixed, TKE_loss, dt, end subroutine itidal_lowmode_loss - +!> This subroutine extracts the energy lost from the propagating internal which has +!> been summed across all angles, frequencies, and modes for a given mechanism and location. +!> It can be called from another module to get values from this module's (private) CS. subroutine get_lowmode_loss(i,j,G,CS,mechanism,TKE_loss_sum) - integer, intent(in) :: i,j - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure - type(int_tide_CS), pointer :: CS - character(len=*), intent(in) :: mechanism - real, intent(out) :: TKE_loss_sum + integer, intent(in) :: i,j + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure + type(int_tide_CS), pointer :: CS + character(len=*), intent(in) :: mechanism + real, intent(out) :: TKE_loss_sum !< Total energy loss rate due to specified + !! mechanism, in W m-2. + ! This subroutine extracts the energy lost from the propagating internal which has ! been summed across all angles, frequencies, and modes for a given mechanism and location. ! It can be called from another module to get values from this module's (private) CS. @@ -795,15 +821,20 @@ subroutine get_lowmode_loss(i,j,G,CS,mechanism,TKE_loss_sum) end subroutine get_lowmode_loss - +!> This subroutine does refraction on the internal waves at a single frequency. subroutine refract(En, cn, freq, dt, G, NAngle, use_PPMang) - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. integer, intent(in) :: NAngle - real, dimension(G%isd:G%ied,G%jsd:G%jed,NAngle), intent(inout) :: En - real, dimension(G%isd:G%ied,G%jsd:G%jed), intent(in) :: cn - real, intent(in) :: freq - real, intent(in) :: dt - logical, intent(in) :: use_PPMang + real, dimension(G%isd:G%ied,G%jsd:G%jed,NAngle), & + intent(inout) :: En !< The internal gravity wave energy density as a + !! function of space and angular resolution, + !! in J m-2 radian-1. + real, dimension(G%isd:G%ied,G%jsd:G%jed), & + intent(in) :: cn !< Baroclinic mode speed, in m s-1. + real, intent(in) :: freq !< Wave frequency, in s-1. + real, intent(in) :: dt !< Time step, in s. + logical, intent(in) :: use_PPMang !< If true, use PPM for advection rather + !! than upwind. ! This subroutine does refraction on the internal waves at a single frequency. ! Arguments: @@ -936,13 +967,17 @@ subroutine refract(En, cn, freq, dt, G, NAngle, use_PPMang) enddo ! j-loop end subroutine refract - +!> This subroutine calculates the 1-d flux for advection in angular space +!! using a monotonic piecewise parabolic scheme. Should be within i and j spatial +!! loops. subroutine PPM_angular_advect(En2d, CFL_ang, Flux_En, NAngle, dt, halo_ang) integer, intent(in) :: NAngle real, intent(in) :: dt integer, intent(in) :: halo_ang - real, dimension(1-halo_ang:NAngle+halo_ang), intent(in) :: En2d - real, dimension(1-halo_ang:NAngle+halo_ang), intent(in) :: CFL_ang + real, dimension(1-halo_ang:NAngle+halo_ang), & + intent(in) :: En2d + real, dimension(1-halo_ang:NAngle+halo_ang), & + intent(in) :: CFL_ang real, dimension(0:NAngle), intent(out) :: Flux_En ! This subroutine calculates the 1-d flux for advection in angular space @@ -1015,14 +1050,18 @@ subroutine PPM_angular_advect(En2d, CFL_ang, Flux_En, NAngle, dt, halo_ang) enddo end subroutine PPM_angular_advect - +!> This subroutine does refraction on the internal waves at a single frequency. subroutine propagate(En, cn, freq, dt, G, CS, NAngle) - type(ocean_grid_type), intent(inout) :: G !< The ocean's grid structure + type(ocean_grid_type), intent(inout) :: G !< The ocean's grid structure. integer, intent(in) :: NAngle - real, dimension(G%isd:G%ied,G%jsd:G%jed,NAngle), intent(inout) :: En - real, dimension(G%isd:G%ied,G%jsd:G%jed), intent(in) :: cn - real, intent(in) :: freq - real, intent(in) :: dt + real, dimension(G%isd:G%ied,G%jsd:G%jed,NAngle), & + intent(inout) :: En !< The internal gravity wave energy density as a + !! function of space and angular resolution, + !! in J m-2 radian-1. + real, dimension(G%isd:G%ied,G%jsd:G%jed), & + intent(in) :: cn !< Baroclinic mode speed, in m s-1. + real, intent(in) :: freq !< Wave frequency, in s-1. + real, intent(in) :: dt !< Time step, in s. type(int_tide_CS), pointer :: CS ! This subroutine does refraction on the internal waves at a single frequency. @@ -1141,16 +1180,23 @@ subroutine propagate(En, cn, freq, dt, G, CS, NAngle) endif end subroutine propagate - +!> This subroutine does first-order corner advection. It was written with the hopes +!! of smoothing out the garden sprinkler effect, but is too numerically diffusive to +!! be of much use as of yet. It is not yet compatible with reflection schemes (BDM). subroutine propagate_corner_spread(En, energized_wedge, NAngle, speed, dt, G, CS, LB) - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure - real, dimension(G%isd:G%ied,G%jsd:G%jed), intent(inout) :: En - real, dimension(G%IsdB:G%IedB,G%Jsd:G%Jed), intent(in) :: speed - integer, intent(in) :: energized_wedge + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. + real, dimension(G%isd:G%ied,G%jsd:G%jed), & + intent(inout) :: En !< The energy density integrated over an angular + !! band, in W m-2, intent in/out. + real, dimension(G%IsdB:G%IedB,G%Jsd:G%Jed), & + intent(in) :: speed !< The magnitude of the group velocity at the cell + !! corner points, in m s-1. + integer, intent(in) :: energized_wedge !< Index of current ray direction. integer, intent(in) :: NAngle - real, intent(in) :: dt - type(int_tide_CS), pointer :: CS - type(loop_bounds_type), intent(in) :: LB + real, intent(in) :: dt !< Time increment in s. + type(int_tide_CS), pointer :: CS !< The control structure returned by a previous + !! call to continuity_PPM_init. + type(loop_bounds_type), intent(in) :: LB !< A structure with the active energy loop bounds. ! This subroutine does first-order corner advection. It was written with the hopes ! of smoothing out the garden sprinkler effect, but is too numerically diffusive to @@ -1411,15 +1457,22 @@ subroutine propagate_corner_spread(En, energized_wedge, NAngle, speed, dt, G, CS enddo; enddo end subroutine propagate_corner_spread +! #@# This subroutine needs a doxygen description subroutine propagate_x(En, speed_x, Cgx_av, dCgx, dt, G, Nangle, CS, LB) - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure - integer, intent(in) :: NAngle - real, dimension(G%isd:G%ied,G%jsd:G%jed,Nangle), intent(inout) :: En - real, dimension(G%IsdB:G%IedB,G%jsd:G%jed), intent(in) :: speed_x - real, dimension(Nangle), intent(in) :: Cgx_av, dCgx - real, intent(in) :: dt - type(int_tide_CS), pointer :: CS - type(loop_bounds_type), intent(in) :: LB + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. + integer, intent(in) :: NAngle + real, dimension(G%isd:G%ied,G%jsd:G%jed,Nangle), & + intent(inout) :: En !< The energy density integrated over an angular + !! band, in J m-2, intent in/out. + real, dimension(G%IsdB:G%IedB,G%jsd:G%jed), & + intent(in) :: speed_x !< The magnitude of the group velocity at the + !! Cu points, in m s-1. + real, dimension(Nangle), intent(in) :: Cgx_av, dCgx + real, intent(in) :: dt !< Time increment in s. + type(int_tide_CS), pointer :: CS !< The control structure returned by a previous call + !! to continuity_PPM_init. + type(loop_bounds_type), intent(in) :: LB !< A structure with the active energy loop bounds. + ! Arguments: En - The energy density integrated over an angular band, in J m-2, ! intent in/out. ! (in) speed_x - The magnitude of the group velocity at the Cu @@ -1493,15 +1546,22 @@ subroutine propagate_x(En, speed_x, Cgx_av, dCgx, dt, G, Nangle, CS, LB) end subroutine propagate_x +! #@# This subroutine needs a doxygen description. subroutine propagate_y(En, speed_y, Cgy_av, dCgy, dt, G, Nangle, CS, LB) - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure - integer, intent(in) :: NAngle - real, dimension(G%isd:G%ied,G%jsd:G%jed,Nangle), intent(inout) :: En - real, dimension(G%isd:G%ied,G%JsdB:G%JedB), intent(in) :: speed_y - real, dimension(Nangle), intent(in) :: Cgy_av, dCgy - real, intent(in) :: dt - type(int_tide_CS), pointer :: CS - type(loop_bounds_type), intent(in) :: LB + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. + integer, intent(in) :: NAngle + real, dimension(G%isd:G%ied,G%jsd:G%jed,Nangle), & + intent(inout) :: En !< The energy density integrated over an angular + !! band, in J m-2, intent in/out. + real, dimension(G%isd:G%ied,G%JsdB:G%JedB), & + intent(in) :: speed_y !< The magnitude of the group velocity at the + !! Cv points, in m s-1. + real, dimension(Nangle), intent(in) :: Cgy_av, dCgy + real, intent(in) :: dt !< Time increment in s. + type(int_tide_CS), pointer :: CS !< The control structure returned by a previous call + !! to continuity_PPM_init. + type(loop_bounds_type), intent(in) :: LB !< A structure with the active energy loop bounds. + ! Arguments: En - The energy density integrated over an angular band, in J m-2, ! intent in/out. ! (in) speed_y - The magnitude of the group velocity at the Cv @@ -1583,17 +1643,23 @@ subroutine propagate_y(En, speed_y, Cgy_av, dCgy, dt, G, Nangle, CS, LB) end subroutine propagate_y - +!> This subroutines evaluates the zonal mass or volume fluxes in a layer. subroutine zonal_flux_En(u, h, hL, hR, uh, dt, G, j, ish, ieh, vol_CFL) - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure - real, dimension(SZIB_(G)), intent(in) :: u !< The zonal velocity, in m s-1 - real, dimension(SZI_(G)), intent(in) :: h - real, dimension(SZI_(G)), intent(in) :: hL - real, dimension(SZI_(G)), intent(in) :: hR - real, dimension(SZIB_(G)), intent(inout) :: uh - real, intent(in) :: dt - integer, intent(in) :: j, ish, ieh - logical, intent(in) :: vol_CFL + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. + real, dimension(SZIB_(G)), intent(in) :: u !< The zonal velocity, in m s-1. + real, dimension(SZI_(G)), intent(in) :: h !< Energy density used to calculate the fluxes, + !! in J m-2. + real, dimension(SZI_(G)), intent(in) :: hL !< Left- Energy densities in the reconstruction, + !! in J m-2. + real, dimension(SZI_(G)), intent(in) :: hR !< Right- Energy densities in the reconstruction, + !! in J m-2. + real, dimension(SZIB_(G)), intent(inout) :: uh !< The zonal energy transport, + !! in J s-1. + real, intent(in) :: dt !< Time increment in s. + integer, intent(in) :: j, ish, ieh !< The index range to work on. + logical, intent(in) :: vol_CFL !< If true, rescale the ratio of face areas to + !! the cell areas when estimating the CFL number. + ! This subroutines evaluates the zonal mass or volume fluxes in a layer. ! ! Arguments: u - Zonal velocity, in m s-1. @@ -1630,15 +1696,23 @@ subroutine zonal_flux_En(u, h, hL, hR, uh, dt, G, j, ish, ieh, vol_CFL) enddo end subroutine zonal_flux_En - +!> This subroutines evaluates the meridional mass or volume fluxes in a layer. subroutine merid_flux_En(v, h, hL, hR, vh, dt, G, J, ish, ieh, vol_CFL) - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure - real, dimension(SZI_(G)), intent(in) :: v !< The meridional velocity, in m s-1 - real, dimension(SZI_(G),SZJ_(G)), intent(in) :: h, hL, hR - real, dimension(SZI_(G)), intent(inout) :: vh - real, intent(in) :: dt - integer, intent(in) :: J, ish, ieh - logical, intent(in) :: vol_CFL + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. + real, dimension(SZI_(G)), intent(in) :: v !< The meridional velocity, in m s-1. + real, dimension(SZI_(G),SZJ_(G)), intent(in) :: h !< Energy density used to calculate the + !! fluxes, in J m-2. + real, dimension(SZI_(G),SZJ_(G)), intent(in) :: hL !< Left- Energy densities in the + !! reconstruction, in J m-2. + real, dimension(SZI_(G),SZJ_(G)), intent(in) :: hR !< Right- Energy densities in the + !! reconstruction, in J m-2. + real, dimension(SZI_(G)), intent(inout) :: vh !< The meridional energy transport, + !! in J s-1. + real, intent(in) :: dt !< Time increment in s. + integer, intent(in) :: J, ish, ieh !< The index range to work on. + logical, intent(in) :: vol_CFL !< If true, rescale the ratio of face + !! areas to the cell areas when estimating + !! the CFL number. ! This subroutines evaluates the meridional mass or volume fluxes in a layer. ! ! Arguments: v - Meridional velocity, in m s-1. @@ -1674,11 +1748,12 @@ subroutine merid_flux_En(v, h, hL, hR, vh, dt, G, J, ish, ieh, vol_CFL) enddo end subroutine merid_flux_En - +!> This subroutine does reflection of the internal waves at a single frequency. subroutine reflect(En, NAngle, CS, G, LB) type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure integer, intent(in) :: NAngle - real, dimension(G%isd:G%ied,G%jsd:G%jed,NAngle), intent(inout) :: En + real, dimension(G%isd:G%ied,G%jsd:G%jed,NAngle), & + intent(inout) :: En type(int_tide_CS), pointer :: CS type(loop_bounds_type), intent(in) :: LB @@ -1790,10 +1865,13 @@ subroutine reflect(En, NAngle, CS, G, LB) end subroutine reflect +!> This subroutine moves energy across lines of partial reflection to prevent +!! reflection of energy that is supposed to get across. subroutine teleport(En, NAngle, CS, G, LB) - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. integer, intent(in) :: NAngle - real, dimension(G%isd:G%ied,G%jsd:G%jed,NAngle), intent(inout) :: En + real, dimension(G%isd:G%ied,G%jsd:G%jed,NAngle), & + intent(inout) :: En type(int_tide_CS), pointer :: CS type(loop_bounds_type), intent(in) :: LB @@ -1888,6 +1966,8 @@ subroutine teleport(En, NAngle, CS, G, LB) end subroutine teleport +!> This subroutine rotates points in the halos where required to accomodate +!! changes in grid orientation, such as at the tripolar fold. subroutine correct_halo_rotation(En, test, G, NAngle) type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure real, dimension(:,:,:,:,:), intent(inout) :: En @@ -1940,12 +2020,17 @@ subroutine correct_halo_rotation(En, test, G, NAngle) enddo end subroutine correct_halo_rotation +!> This subroutine calculates left/right edge values for PPM reconstruction. subroutine PPM_reconstruction_x(h_in, h_l, h_r, G, LB, simple_2nd) - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure - real, dimension(SZI_(G),SZJ_(G)), intent(in) :: h_in - real, dimension(SZI_(G),SZJ_(G)), intent(out) :: h_l, h_r - type(loop_bounds_type), intent(in) :: LB - logical, optional, intent(in) :: simple_2nd + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. + real, dimension(SZI_(G),SZJ_(G)), intent(in) :: h_in !< Energy density in a sector (2D). + real, dimension(SZI_(G),SZJ_(G)), intent(out) :: h_l !< Left edge value of reconstruction (2D). + real, dimension(SZI_(G),SZJ_(G)), intent(out) :: h_r !< Right edge value of reconstruction (2D). + type(loop_bounds_type), intent(in) :: LB !< A structure with the active loop bounds. + logical, optional, intent(in) :: simple_2nd !< If true, use the arithmetic mean + !! energy densities as default edge values + !! for a simple 2nd order scheme. + ! This subroutine calculates left/right edge values for PPM reconstruction. ! Arguments: h_in - Energy density in a sector (2D) ! (out) h_l,h_r - left/right edge value of reconstruction (2D) @@ -2020,13 +2105,17 @@ subroutine PPM_reconstruction_x(h_in, h_l, h_r, G, LB, simple_2nd) call PPM_limit_pos(h_in, h_l, h_r, 0.0, G, isl, iel, jsl, jel) end subroutine PPM_reconstruction_x - +!> This subroutine calculates left/right edge valus for PPM reconstruction. subroutine PPM_reconstruction_y(h_in, h_l, h_r, G, LB, simple_2nd) - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure - real, dimension(SZI_(G),SZJ_(G)), intent(in) :: h_in - real, dimension(SZI_(G),SZJ_(G)), intent(out) :: h_l, h_r - type(loop_bounds_type), intent(in) :: LB - logical, optional, intent(in) :: simple_2nd + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. + real, dimension(SZI_(G),SZJ_(G)), intent(in) :: h_in !< Energy density in a sector (2D). + real, dimension(SZI_(G),SZJ_(G)), intent(out) :: h_l !< Left edge value of reconstruction (2D). + real, dimension(SZI_(G),SZJ_(G)), intent(out) :: h_r !< Right edge value of reconstruction (2D). + type(loop_bounds_type), intent(in) :: LB !< A structure with the active loop bounds. + logical, optional, intent(in) :: simple_2nd !< If true, use the arithmetic mean + !! energy densities as default edge values + !! for a simple 2nd order scheme. + ! This subroutine calculates left/right edge valus for PPM reconstruction. ! Arguments: h_in - Energy density in a sector (2D) ! (out) h_l,h_r - left/right edge value of reconstruction (2D) @@ -2099,13 +2188,20 @@ subroutine PPM_reconstruction_y(h_in, h_l, h_r, G, LB, simple_2nd) call PPM_limit_pos(h_in, h_l, h_r, 0.0, G, isl, iel, jsl, jel) end subroutine PPM_reconstruction_y - +!> This subroutine limits the left/right edge values of the PPM reconstruction +!! to give a reconstruction that is positive-definite. Here this is +!! reinterpreted as giving a constant thickness if the mean thickness is less +!! than h_min, with a minimum of h_min otherwise. subroutine PPM_limit_pos(h_in, h_L, h_R, h_min, G, iis, iie, jis, jie) - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure - real, dimension(SZI_(G),SZJ_(G)), intent(in) :: h_in - real, dimension(SZI_(G),SZJ_(G)), intent(inout) :: h_L, h_R - real, intent(in) :: h_min - integer, intent(in) :: iis, iie, jis, jie + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. + real, dimension(SZI_(G),SZJ_(G)), intent(in) :: h_in !< Thickness of layer (2D). + real, dimension(SZI_(G),SZJ_(G)), intent(inout) :: h_L !< Left edge value (2D). + real, dimension(SZI_(G),SZJ_(G)), intent(inout) :: h_R !< Right edge value (2D). + real, intent(in) :: h_min !< The minimum thickness that can be + !! obtained by a concave parabolic fit. + integer, intent(in) :: iis, iie, jis, jie !< Index range for + !! computation. + ! This subroutine limits the left/right edge values of the PPM reconstruction ! to give a reconstruction that is positive-definite. Here this is ! reinterpreted as giving a constant thickness if the mean thickness is less @@ -2199,13 +2295,18 @@ end subroutine PPM_limit_pos ! end subroutine register_int_tide_restarts +! #@# This subroutine needs a doxygen comment. subroutine internal_tides_init(Time, G, GV, param_file, diag, CS) - type(time_type), target, intent(in) :: Time - type(ocean_grid_type), intent(inout) :: G !< The ocean's grid structure - type(verticalGrid_type), intent(in) :: GV !< The ocean's vertical grid structure - type(param_file_type), intent(in) :: param_file !< A structure to parse for run-time parameters - type(diag_ctrl), target, intent(in) :: diag - type(int_tide_CS),pointer :: CS + type(time_type), target, intent(in) :: Time !< The current model time. + type(ocean_grid_type), intent(inout) :: G !< The ocean's grid structure. + type(verticalGrid_type), intent(in) :: GV !< The ocean's vertical grid structure. + type(param_file_type), intent(in) :: param_file !< A structure to parse for run-time + !! parameters. + type(diag_ctrl), target, intent(in) :: diag !< A structure that is used to regulate + !! diagnostic output. + type(int_tide_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) GV - The ocean's vertical grid structure. diff --git a/src/tracer/MOM_tracer_flow_control.F90 b/src/tracer/MOM_tracer_flow_control.F90 index c2e889266b..153f000693 100644 --- a/src/tracer/MOM_tracer_flow_control.F90 +++ b/src/tracer/MOM_tracer_flow_control.F90 @@ -119,17 +119,21 @@ module MOM_tracer_flow_control contains -! The following 5 subroutines and associated definitions provide the -! machinery to register and call the subroutines that initialize -! tracers and apply vertical column processes to tracers. - +!> The following 5 subroutines and associated definitions provide the +!! machinery to register and call the subroutines that initialize +!! tracers and apply vertical column processes to tracers. subroutine call_tracer_register(HI, GV, param_file, CS, tr_Reg, restart_CS) - type(hor_index_type), intent(in) :: HI - type(verticalGrid_type), intent(in) :: GV !< The ocean's vertical grid structure - type(param_file_type), intent(in) :: param_file !< A structure to parse for run-time parameters - type(tracer_flow_control_CS), pointer :: CS - type(tracer_registry_type), pointer :: tr_Reg - type(MOM_restart_CS), pointer :: restart_CS + type(hor_index_type), intent(in) :: HI !< A horizontal index type structure. + type(verticalGrid_type), intent(in) :: GV !< The ocean's vertical grid structure. + type(param_file_type), intent(in) :: param_file !< A structure to parse for run-time + !! parameters. + type(tracer_flow_control_CS), pointer :: CS !< A pointer that is set to point to the + !! control structure for this module. + type(tracer_registry_type), pointer :: tr_Reg !< A pointer that is set to point to the + !! control structure for the tracer + !! advection and diffusion module. + type(MOM_restart_CS), pointer :: restart_CS !< A pointer to the restart control + !! structure. ! Arguments: HI - A horizontal index type structure. ! (in) GV - The ocean's vertical grid structure. ! (in) param_file - A structure indicating the open file to parse for @@ -236,21 +240,39 @@ subroutine call_tracer_register(HI, GV, param_file, CS, tr_Reg, restart_CS) end subroutine call_tracer_register +!> This subroutine calls all registered tracer initialization +!! subroutines. subroutine tracer_flow_control_init(restart, day, G, GV, h, param_file, diag, OBC, & CS, sponge_CSp, ALE_sponge_CSp, diag_to_Z_CSp, tv) - logical, intent(in) :: restart - type(time_type), target, intent(in) :: day - type(ocean_grid_type), intent(inout) :: G !< The ocean's grid structure - type(verticalGrid_type), intent(in) :: GV !< The ocean's vertical grid structure - real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(in) :: h !< Layer thicknesses, in H (usually m or kg m-2) - type(param_file_type), intent(in) :: param_file !< A structure to parse for run-time parameters - type(diag_ctrl), target, intent(in) :: diag - type(ocean_OBC_type), pointer :: OBC - type(tracer_flow_control_CS), pointer :: CS - type(sponge_CS), pointer :: sponge_CSp - type(ALE_sponge_CS), pointer :: ALE_sponge_CSp - type(diag_to_Z_CS), pointer :: diag_to_Z_CSp - type(thermo_var_ptrs), intent(in) :: tv !< A structure pointing to various thermodynamic variables + logical, intent(in) :: restart !< 1 if the fields have already + !! been read from a restart file. + type(time_type), target, intent(in) :: day !< Time of the start of the run. + type(ocean_grid_type), intent(inout) :: G !< The ocean's grid structure. + type(verticalGrid_type), intent(in) :: GV !< The ocean's vertical grid + !! structure. + real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(in) :: h !< Layer thicknesses, in H + !! (usually m or kg m-2) + type(param_file_type), intent(in) :: param_file !< A structure to parse for + !! run-time parameters + type(diag_ctrl), target, intent(in) :: diag !< A structure that is used to + !! regulate diagnostic output. + type(ocean_OBC_type), pointer :: OBC !< This open boundary condition + !! type specifies whether, where, + !! and what open boundary + !! conditions are used. + type(tracer_flow_control_CS), pointer :: CS !< The control structure returned + !! by a previous call to + !! call_tracer_register. + type(sponge_CS), pointer :: sponge_CSp !< A pointer to the control + !! structure for the sponges, if they are in use. + !! Otherwise this may be unassociated. + type(ALE_sponge_CS), pointer :: ALE_sponge_CSp !< A pointer to the control + !! structure for the ALE sponges, if they are in use. + !! Otherwise this may be unassociated. + type(diag_to_Z_CS), pointer :: diag_to_Z_CSp !< A pointer to the control + !! structure for diagnostics in depth space. + type(thermo_var_ptrs), intent(in) :: tv !< A structure pointing to various + !! thermodynamic variables ! This subroutine calls all registered tracer initialization ! subroutines. @@ -267,7 +289,8 @@ subroutine tracer_flow_control_init(restart, day, G, GV, h, param_file, diag, OB ! call_tracer_register. ! (in/out) sponge_CSp - A pointer to the control structure for the sponges, if ! they are in use. Otherwise this may be unassociated. -! (in/out) ALE_sponge_CSp - A pointer to the control structure for the ALE sponges, if they are in use. Otherwise this may be unassociated. +! (in/out) ALE_sponge_CSp - A pointer to the control structure for the ALE sponges, if they are +! in use. Otherwise this may be unassociated. ! (in/out) diag_to_Z_Csp - A pointer to the control structure for diagnostics ! in depth space. if (.not. associated(CS)) call MOM_error(FATAL, "tracer_flow_control_init: "// & @@ -312,10 +335,16 @@ subroutine tracer_flow_control_init(restart, day, G, GV, h, param_file, diag, OB end subroutine tracer_flow_control_init +! #@# This subroutine needs a doxygen description subroutine get_chl_from_model(Chl_array, G, CS) - real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(out) :: Chl_array - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure - type(tracer_flow_control_CS), pointer :: CS + real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(out) :: Chl_array !< The array into which the + !! model's Chlorophyll-A + !! concentrations in mg m-3 are + !! to be read. + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. + type(tracer_flow_control_CS), pointer :: CS !< The control structure returned + !! by a previous call to + !! call_tracer_register. ! Arguments: Chl_array - The array into which the model's Chlorophyll-A ! concentrations in mg m-3 are to be read. ! (in) G - The ocean's grid structure. @@ -339,14 +368,23 @@ subroutine get_chl_from_model(Chl_array, G, CS) end subroutine get_chl_from_model +!> This subroutine calls the individual tracer modules' subroutines to +!! specify or read quantities related to their surface forcing. subroutine call_tracer_set_forcing(state, fluxes, day_start, day_interval, G, CS) - type(surface), intent(inout) :: state - type(forcing), intent(inout) :: fluxes - type(time_type), intent(in) :: day_start - type(time_type), intent(in) :: day_interval - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure - type(tracer_flow_control_CS), pointer :: CS + type(surface), intent(inout) :: state !< A structure containing fields that + !! describe the surface state of the + !! ocean. + type(forcing), intent(inout) :: fluxes !< A structure containing pointers to any + !! possible forcing fields. Unused fields + !! have NULL ptrs. + type(time_type), intent(in) :: day_start !< Start time of the fluxes. + type(time_type), intent(in) :: day_interval !< Length of time over which these + !! fluxes will be applied. + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. + type(tracer_flow_control_CS), pointer :: CS !< The control structure returned by a + !! previous call to call_tracer_register. + ! This subroutine calls the individual tracer modules' subroutines to ! specify or read quantities related to their surface forcing. ! Arguments: state - A structure containing fields that describe the @@ -368,20 +406,44 @@ subroutine call_tracer_set_forcing(state, fluxes, day_start, day_interval, G, CS end subroutine call_tracer_set_forcing +!> This subroutine calls all registered tracer column physics +!! subroutines. subroutine call_tracer_column_fns(h_old, h_new, ea, eb, fluxes, Hml, dt, G, GV, tv, optics, CS, & debug, evap_CFL_limit, minimum_forcing_depth) - real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(in) :: h_old, h_new, ea, eb - type(forcing), intent(in) :: fluxes - real, dimension(NIMEM_,NJMEM_), intent(in) :: Hml !< Mixed layer depth (m) - real, intent(in) :: dt !< The amount of time covered by this call, in s - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure - type(verticalGrid_type), intent(in) :: GV !< The ocean's vertical grid structure - type(thermo_var_ptrs), intent(in) :: tv !< A structure pointing to various thermodynamic variables - type(optics_type), pointer :: optics - type(tracer_flow_control_CS), pointer :: CS - logical, intent(in) :: debug - real, optional,intent(in) :: evap_CFL_limit - real, optional,intent(in) :: minimum_forcing_depth + real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(in) :: h_old !< Layer thickness before entrainment, + !! in m (Boussinesq) or kg m-2 + !! (non-Boussinesq). + real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(in) :: h_new !< Layer thickness after entrainment, + !! in m or kg m-2. + real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(in) :: ea !< an array to which the amount of + !! fluid entrained from the layer above during this call + !! will be added, in m or kg m-2, the same as h_old. + real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(in) :: eb !< an array to which the amount of + !! fluid entrained from the layer below during this call + !! will be added, in m or kg m-2, the same as h_old. + type(forcing), intent(in) :: fluxes !< A structure containing pointers to + !! any possible forcing fields. + !! Unused fields have NULL ptrs. + real, dimension(NIMEM_,NJMEM_), intent(in) :: Hml !< Mixed layer depth (m) + real, intent(in) :: dt !< The amount of time covered by this + !! call, in s + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. + type(verticalGrid_type), intent(in) :: GV !< The ocean's vertical grid + !! structure. + type(thermo_var_ptrs), intent(in) :: tv !< A structure pointing to various + !! thermodynamic variables. + type(optics_type), pointer :: optics !< The structure containing optical + !! properties. + type(tracer_flow_control_CS), pointer :: CS !< The control structure returned by + !! a previous call to + !! call_tracer_register. + logical, intent(in) :: debug !< Calculates checksums + real, optional,intent(in) :: evap_CFL_limit !< Limits how much water + !! can be fluxed out of the top layer + !! Stored previously in diabatic] CS. + real, optional,intent(in) :: minimum_forcing_depth !< The smallest depth + !! over which fluxes can be applied + !! Stored previously in diabatic CS. ! This subroutine calls all registered tracer column physics ! subroutines. @@ -517,21 +579,39 @@ subroutine call_tracer_column_fns(h_old, h_new, ea, eb, fluxes, Hml, dt, G, GV, end subroutine call_tracer_column_fns - +!> This subroutine calls all registered tracer packages to enable them to +!! add to the surface state returned to the coupler. These routines are optional. subroutine call_tracer_stocks(h, stock_values, G, GV, CS, stock_names, stock_units, & - num_stocks, stock_index, got_min_max,global_min, global_max,xgmin, ygmin, zgmin, xgmax, ygmax, zgmax) - real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(in) :: h !< Layer thicknesses, in H (usually m or kg m-2) - real, dimension(:), intent(out) :: stock_values - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure - type(verticalGrid_type), intent(in) :: GV !< The ocean's vertical grid structure - type(tracer_flow_control_CS), pointer :: CS - character(len=*), dimension(:), optional, intent(out) :: stock_names - character(len=*), dimension(:), optional, intent(out) :: stock_units - integer, optional, intent(out) :: num_stocks - integer, optional, intent(in) :: stock_index - logical, dimension(:), optional, intent(inout) :: got_min_max - real, dimension(:), optional, intent(out) :: global_min, global_max - real, dimension(:), optional, intent(out) :: xgmin, ygmin, zgmin, xgmax, ygmax, zgmax + num_stocks, stock_index, got_min_max,global_min, global_max,xgmin, & + ygmin, zgmin, xgmax, ygmax, zgmax) + real, dimension(NIMEM_,NJMEM_,NKMEM_), & + intent(in) :: h !< Layer thicknesses, in H + !! (usually m or kg m-2). + real, dimension(:), intent(out) :: stock_values + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. + type(verticalGrid_type), intent(in) :: GV !< The ocean's vertical grid structure. + type(tracer_flow_control_CS), pointer :: CS !< The control structure returned by a + !! previous call to + !! call_tracer_register. + character(len=*), dimension(:), optional, & + intent(out) :: stock_names !< Diagnostic names to use for each + !! stock. + character(len=*), dimension(:), optional, & + intent(out) :: stock_units !< Units to use in the metadata for + !! each stock. + integer, optional, & + intent(out) :: num_stocks !< The number of tracer stocks being + !! returned. + integer, optional, & + intent(in) :: stock_index !< The integer stock index from + !! stocks_constans_mod of the stock to be returned. If this is + !! present and greater than 0, only a single stock can be returned. + logical, dimension(:), optional, & + intent(inout) :: got_min_max + real, dimension(:), optional, & + intent(out) :: global_min, global_max + real, dimension(:), optional, & + intent(out) :: xgmin, ygmin, zgmin, xgmax, ygmax, zgmax ! This subroutine calls all registered tracer packages to enable them to ! add to the surface state returned to the coupler. These routines are optional. @@ -638,6 +718,7 @@ subroutine call_tracer_stocks(h, stock_values, G, GV, CS, stock_names, stock_uni end subroutine call_tracer_stocks +!> This routine stores the stocks and does error handling for call_tracer_stocks. subroutine store_stocks(pkg_name, ns, names, units, values, index, stock_values, & set_pkg_name, max_ns, ns_tot, stock_names, stock_units) character(len=*), intent(in) :: pkg_name @@ -686,11 +767,17 @@ subroutine store_stocks(pkg_name, ns, names, units, values, index, stock_values, end subroutine store_stocks +!> This subroutine calls all registered tracer packages to enable them to +!! add to the surface state returned to the coupler. These routines are optional. subroutine call_tracer_surface_state(state, h, G, CS) - type(surface), intent(inout) :: state - real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(in) :: h !< Layer thicknesses, in H (usually m or kg m-2) - type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure - type(tracer_flow_control_CS), pointer :: CS + type(surface), intent(inout) :: state !< A structure containing fields that + !! describe the surface state of the ocean. + real, dimension(NIMEM_,NJMEM_,NKMEM_), & + intent(in) :: h !< Layer thicknesses, in H + !! (usually m or kg m-2). + type(ocean_grid_type), intent(in) :: G !< The ocean's grid structure. + type(tracer_flow_control_CS), pointer :: CS !< The control structure returned by a + !! previous call to call_tracer_register. ! This subroutine calls all registered tracer packages to enable them to ! add to the surface state returned to the coupler. These routines are optional.