mom_kappa_shear module reference¶

Shear-dependent mixing following Jackson et al. 2008.

Data Types¶

kappa_shear_cs

This control structure holds the parameters that regulate shear mixing.

Functions/Subroutines¶

`calculate_kappa_shear()`	Subroutine for calculating shear-driven diffusivity and TKE in tracer columns.
`calc_kappa_shear_vertex()`	Subroutine for calculating shear-driven diffusivity and TKE in corner columns.
`kappa_shear_column()`	This subroutine calculates shear-driven diffusivity and TKE in a single column.
`calculate_projected_state()`	This subroutine calculates the velocities, temperature and salinity that the water column will have after mixing for dt with diffusivities kappa.
`find_kappa_tke()`	This subroutine calculates new, consistent estimates of TKE and kappa.
`kappa_shear_init()`	This subroutine initializes the parameters that regulate shear-driven mixing.
`kappa_shear_is_used()`	This function indicates to other modules whether the Jackson et al shear mixing parameterization will be used without needing to duplicate the log entry.
`kappa_shear_at_vertex()`	This function indicates to other modules whether the Jackson et al shear mixing parameterization will be used at the vertices without needing to duplicate the log entry.

Detailed Description¶

By Laura Jackson and Robert Hallberg, 2006-2008.

This file contains the subroutines that determine the diapycnal diffusivity driven by resolved shears, as specified by the parameterizations described in Jackson and Hallberg (JPO, 2008).

The technique by which the 6 equations (for kappa, TKE, u, v, T, and S) are solved simultaneously has been dramatically revised from the previous version. The previous version was not converging in some cases, especially near the surface mixed layer, while the revised version does. The revised version solves for kappa and TKE with shear and stratification fixed, then marches the density and velocities forward with an adaptive (and aggressive) time step in a predictor-corrector-corrector emulation of a trapezoidal scheme. Run-time-settable parameters determine the tolerance to which the kappa and TKE equations are solved and the minimum time step that can be taken.

Type Documentation¶

type mom_kappa_shear/kappa_shear_cs¶

This control structure holds the parameters that regulate shear mixing.

Type fields:

% id_kd_shear [integer] :: Diagnostic IDs.
% id_tke [integer] :: Diagnostic IDs.
% rino_crit [real] :: The critical shear Richardson number for shear-entrainment [nondim]. The theoretical value is 0.25. The values found by Jackson et al. are 0.25-0.35.
% shearmix_rate [real] :: A nondimensional rate scale for shear-driven entrainment [nondim]. The value given by Jackson et al. is 0.085-0.089.
% fri_curvature [real] :: A constant giving the curvature of the function of the Richardson number that relates shear to sources in the kappa equation [nondim]. The values found by Jackson et al. are -0.97 - -0.89.
% c_n [real] :: The coefficient for the decay of TKE due to stratification (i.e. proportional to N*tke) [nondim]. The values found by Jackson et al. are 0.24-0.28.
% c_s [real] :: The coefficient for the decay of TKE due to shear (i.e. proportional to |S|*tke) [nondim]. The values found by Jackson et al. are 0.14-0.12.
% lambda [real] :: The coefficient for the buoyancy length scale in the kappa equation [nondim]. The values found by Jackson et al. are 0.82-0.81.
% lambda2_n_s [real] :: The square of the ratio of the coefficients of the buoyancy and shear scales in the diffusivity equation, 0 to eliminate the shear scale [nondim].
% tke_bg [real] :: The background level of TKE [Z2 T-2 ~> m2 s-2].
% kappa_0 [real] :: The background diapycnal diffusivity [H Z T-1 ~> m2 s-1 or Pa s].
% kappa_seed [real] :: A moderately large seed value of diapycnal diffusivity that is used as a starting turbulent diffusivity in the iterations to findind an energetically constrained solution for the shear-driven diffusivity [H Z T-1 ~> m2 s-1 or Pa s].
% kappa_trunc [real] :: Diffusivities smaller than this are rounded to 0 [H Z T-1 ~> m2 s-1 or Pa s].
% kappa_tol_err [real] :: The fractional error in kappa that is tolerated [nondim].
% prandtl_turb [real] :: Prandtl number used to convert Kd_shear into viscosity [nondim].
% nkml [integer] :: The number of layers in the mixed layer, as treated in this routine. If the pieces of the mixed layer are not to be treated collectively, nkml is set to 1.
% max_rino_it [integer] :: The maximum number of iterations that may be used to estimate the instantaneous shear-driven mixing.
% max_ks_it [integer] :: The maximum number of iterations that may be used to estimate the time-averaged diffusivity.
% dkdq_iteration_bug [logical] :: If true. use an older, dimensionally inconsistent estimate of the derivative of diffusivity with energy in the Newton’s method iteration. The bug causes undercorrections when dz > 1m.
% ks_at_vertex [logical] :: If true, do the calculations of the shear-driven mixing at the cell vertices (i.e., the vorticity points).
% eliminate_massless [logical] :: If true, massless layers are merged with neighboring massive layers in this calculation.
% vel_underflow [real] :: Velocity components smaller than vel_underflow are set to 0 [L T-1 ~> m s-1].
% kappa_src_max_chg [real] :: The maximum permitted increase in the kappa source within an iteration relative to the local source [nondim]. This must be greater than 1. The lower limit for the permitted fractional decrease is (1 - 0.5/kappa_src_max_chg). These limits could perhaps be made dynamic with an improved iterative solver.
% psurf_bug [logical] :: If true, do a simple average of the cell surface pressures to get a surface pressure at the corner if VERTEX_SHEAR=True. Otherwise mask out any land points in the average.
% all_layer_tke_bug [logical] :: If true, report back the latest estimate of TKE instead of the time average TKE when there is mass in all layers. Otherwise always report the time-averaged TKE, as is currently done when there are some massless layers.
% restrictive_tolerance_check [logical] :: If false, uses the less restrictive tolerance check to determine if a timestep is acceptable for the KS_it outer iteration loop, as the code was originally written. True uses the more restrictive check.
% debug [logical] :: If true, write verbose debugging messages.
% diag [type( diag_ctrl ),pointer] :: A structure that is used to regulate the timing of diagnostic output.

Function/Subroutine Documentation¶

subroutine mom_kappa_shear/calculate_kappa_shear(u_in, v_in, h, tv, p_surf, kappa_io, tke_io, kv_io, dt, G, GV, US, CS)¶

Subroutine for calculating shear-driven diffusivity and TKE in tracer columns.

Parameters:

g :: [in] The ocean’s grid structure.
gv :: [in] The ocean’s vertical grid structure.
us :: [in] A dimensional unit scaling type
u_in :: [in] Initial zonal velocity [L T-1 ~> m s-1].
v_in :: [in] Initial meridional velocity [L T-1 ~> m s-1].
h :: [in] Layer thicknesses [H ~> m or kg m-2].
tv :: [in] A structure containing pointers to any available thermodynamic fields. Absent fields have NULL ptrs.
p_surf :: The pressure at the ocean surface [R L2 T-2 ~> Pa] (or NULL).
kappa_io :: [inout] The diapycnal diffusivity at each interface
tke_io :: [out] The turbulent kinetic energy per unit mass at
kv_io :: [inout] The vertical viscosity at each interface
dt :: [in] Time increment [T ~> s].
cs :: The control structure returned by a previous call to kappa_shear_init.

Call to:

kappa_shear_column

subroutine mom_kappa_shear/calc_kappa_shear_vertex(u_in, v_in, h, T_in, S_in, tv, p_surf, kappa_io, tke_io, kv_io, dt, G, GV, US, CS)¶

Subroutine for calculating shear-driven diffusivity and TKE in corner columns.

Parameters:

g :: [in] The ocean’s grid structure.
gv :: [in] The ocean’s vertical grid structure.
us :: [in] A dimensional unit scaling type
u_in :: [in] Initial zonal velocity [L T-1 ~> m s-1].
v_in :: [in] Initial meridional velocity [L T-1 ~> m s-1].
h :: [in] Layer thicknesses [H ~> m or kg m-2].
t_in :: [in] Layer potential temperatures [C ~> degC]
s_in :: [in] Layer salinities [S ~> ppt]
tv :: [in] A structure containing pointers to any available thermodynamic fields. Absent fields have NULL ptrs.
p_surf :: The pressure at the ocean surface [R L2 T-2 ~> Pa] (or NULL).
kappa_io :: [out] The diapycnal diffusivity at each interface
tke_io :: [out] The turbulent kinetic energy per unit mass at
kv_io :: [inout] The vertical viscosity at each interface
dt :: [in] Time increment [T ~> s].
cs :: The control structure returned by a previous call to kappa_shear_init.

Call to:

kappa_shear_column

Called from:

mom_set_diffusivity::set_diffusivity

subroutine mom_kappa_shear/kappa_shear_column(kappa, tke, dt, nzc, f2, surface_pres, hlay, dz_lay, u0xdz, v0xdz, T0xdz, S0xdz, kappa_avg, tke_avg, tv, CS, GV, US)¶

This subroutine calculates shear-driven diffusivity and TKE in a single column.

Parameters:

gv :: [in] The ocean’s vertical grid structure.
kappa :: [inout] The time-weighted average of kappa [H Z T-1 ~> m2 s-1 or Pa s]
tke :: [out] The Turbulent Kinetic Energy per unit mass at
nzc :: [in] The number of active layers in the column.
f2 :: [in] The square of the Coriolis parameter [T-2 ~> s-2].
surface_pres :: [in] The surface pressure [R L2 T-2 ~> Pa].
hlay :: [in] The layer thickness [H ~> m or kg m-2]
dz_lay :: [in] The geometric layer thickness in height units [Z ~> m]
u0xdz :: [in] The initial zonal velocity times hlay [H L T-1 ~> m2 s-1 or kg m-1 s-1]
v0xdz :: [in] The initial meridional velocity times the
t0xdz :: [in] The initial temperature times hlay [C H ~> degC m or degC kg m-2]
s0xdz :: [in] The initial salinity times hlay [S H ~> ppt m or ppt kg m-2]
kappa_avg :: [out] The time-weighted average of kappa [H Z T-1 ~> m2 s-1 or Pa s]
tke_avg :: [out] The time-weighted average of TKE [Z2 T-2 ~> m2 s-2].
dt :: [in] Time increment [T ~> s].
tv :: [in] A structure containing pointers to any available thermodynamic fields. Absent fields have NULL ptrs.
cs :: The control structure returned by a previous call to kappa_shear_init.
us :: [in] A dimensional unit scaling type

Call to:

calculate_projected_state find_kappa_tke

Called from:

calc_kappa_shear_vertex calculate_kappa_shear

subroutine mom_kappa_shear/calculate_projected_state(kappa, u0, v0, T0, S0, dt, nz, dz, I_dz_int, dbuoy_dT, dbuoy_dS, vel_under, u, v, T, Sal, N2, S2, GV, US, ks_int, ke_int)¶

This subroutine calculates the velocities, temperature and salinity that the water column will have after mixing for dt with diffusivities kappa. It may also calculate the projected buoyancy frequency and shear.

Parameters:

nz :: [in] The number of layers (after eliminating massless layers?).
kappa :: [in] The diapycnal diffusivity at interfaces, [H Z T-1 ~> m2 s-1 or Pa s].
u0 :: [in] The initial zonal velocity [L T-1 ~> m s-1].
v0 :: [in] The initial meridional velocity [L T-1 ~> m s-1].
t0 :: [in] The initial temperature [C ~> degC].
s0 :: [in] The initial salinity [S ~> ppt].
dt :: [in] The time step [T ~> s].
dz :: [in] The layer thicknesses [H ~> m or kg m-2]
i_dz_int :: [in] The inverse of the distance between succesive layer centers [Z-1 ~> m-1].
dbuoy_dt :: [in] The partial derivative of buoyancy with temperature [Z T-2 C-1 ~> m s-2 degC-1].
dbuoy_ds :: [in] The partial derivative of buoyancy with salinity [Z T-2 S-1 ~> m s-2 ppt-1].
vel_under :: [in] Any velocities that are smaller in magnitude than this value are set to 0 [L T-1 ~> m s-1].
u :: [inout] The zonal velocity after dt [L T-1 ~> m s-1].
v :: [inout] The meridional velocity after dt [L T-1 ~> m s-1].
t :: [inout] The temperature after dt [C ~> degC].
sal :: [inout] The salinity after dt [S ~> ppt].
n2 :: [inout] The buoyancy frequency squared at interfaces [T-2 ~> s-2].
s2 :: [inout] The squared shear at interfaces [T-2 ~> s-2].
gv :: [in] The ocean’s vertical grid structure.
us :: [in] A dimensional unit scaling type
ks_int :: [in] The topmost k-index with a non-zero diffusivity.
ke_int :: [in] The bottommost k-index with a non-zero diffusivity.

Called from:

kappa_shear_column

subroutine mom_kappa_shear/find_kappa_tke(N2, S2, kappa_in, Idz, h_Int, dz_Int, dz_h_Int, I_L2_bdry, f2, nz, CS, GV, US, K_Q, tke, kappa, kappa_src, local_src)¶

This subroutine calculates new, consistent estimates of TKE and kappa.

Parameters:

nz :: [in] The number of layers to work on.
n2 :: [in] The buoyancy frequency squared at interfaces [T-2 ~> s-2].
s2 :: [in] The squared shear at interfaces [T-2 ~> s-2].
kappa_in :: [in] The initial guess at the diffusivity [H Z T-1 ~> m2 s-1 or Pa s]
h_int :: [in] The thicknesses associated with interfaces [H ~> m or kg m-2]
dz_int :: [in] The vertical distances around interfaces [Z ~> m]
dz_h_int :: [in] The ratio of the vertical distances to the thickness around an interface [Z H-1 ~> nondim or m3 kg-1]. In non-Boussinesq mode this is the specific volume.
i_l2_bdry :: [in] The inverse of the squared distance to boundaries [H-1 Z-1 ~> m-2 or m kg-1].
idz :: [in] The inverse grid spacing of layers [Z-1 ~> m-1].
f2 :: [in] The squared Coriolis parameter [T-2 ~> s-2].
cs :: A pointer to this module’s control structure.
gv :: [in] The ocean’s vertical grid structure.
us :: [in] A dimensional unit scaling type
k_q :: [inout] The shear-driven diapycnal diffusivity divided by the turbulent kinetic energy per unit mass at interfaces [H T Z-1 ~> s or kg s m-3].
tke :: [out] The turbulent kinetic energy per unit mass at interfaces [Z2 T-2 ~> m2 s-2].
kappa :: [out] The diapycnal diffusivity at interfaces [H Z T-1 ~> m2 s-1 or Pa s]
kappa_src :: [out] The source term for kappa [T-1 ~> s-1]
local_src :: [out] The sum of all local sources for kappa

Called from:

kappa_shear_column

function mom_kappa_shear/kappa_shear_init(Time, G, GV, US, param_file, diag, CS) [logical]¶

This subroutine initializes the parameters that regulate shear-driven mixing.

Parameters:

time :: [in] The current model time.
g :: [in] The ocean’s grid structure.
gv :: [in] The ocean’s vertical grid structure.
us :: [in] A dimensional unit scaling type
param_file :: [in] A structure to parse for run-time parameters.
diag :: [inout] A structure that is used to regulate diagnostic output.
cs :: A pointer that is set to point to the control structure for this module

Return:

undefined :: True if module is to be used, False otherwise

Call to:

mom_error_handler::mom_error

function mom_kappa_shear/kappa_shear_is_used(param_file) [logical]¶

This function indicates to other modules whether the Jackson et al shear mixing parameterization will be used without needing to duplicate the log entry.

Parameters:: param_file :: [in] A structure to parse for run-time parameters
Called from:: mom_cvmix_shear::cvmix_shear_init mom_diabatic_driver::diabatic_driver_init mom_set_visc::set_visc_init mom_set_visc::set_visc_register_restarts

function mom_kappa_shear/kappa_shear_at_vertex(param_file) [logical]¶

This function indicates to other modules whether the Jackson et al shear mixing parameterization will be used at the vertices without needing to duplicate the log entry. It returns false if the Jackson et al scheme is not used or if it is used via calculations at the tracer points.

Parameters:: param_file :: [in] A structure to parse for run-time parameters
Called from:: mom_set_diffusivity::set_diffusivity_init mom_set_visc::set_visc_init mom_set_visc::set_visc_register_restarts