mom_kappa_shear module reference

Shear-dependent mixing following Jackson et al. 2008.

More…

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 tolerence 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.

  • % id_ild2 [integer] :: Diagnostic IDs.

  • % id_dz_int [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 [Z2 T-1 ~> m2 s-1].

  • % kappa_trunc [real] :: Diffusivities smaller than this are rounded to 0 [Z2 T-1 ~> m2 s-1].

  • % 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, initialize_all)

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.

  • initialize_all :: [in] If present and false, the previous value of kappa is used to start the iterations

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, initialize_all)

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 [degC]

  • s_in :: [in] Layer salinities in 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 [Z2 T-1 ~> m2 s-1].

  • dt :: [in] Time increment [T ~> s].

  • cs :: The control structure returned by a previous call to kappa_shear_init.

  • initialize_all :: [in] If present and false, the previous value of kappa is used to start the iterations

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, dz, u0xdz, v0xdz, T0xdz, S0xdz, kappa_avg, tke_avg, tv, CS, GV, US, I_Ld2_1d, dz_Int_1d)

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 [Z2 T-1 ~> m2 s-1].

  • 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].

  • dz :: [in] The layer thickness [Z ~> m].

  • u0xdz :: [in] The initial zonal velocity times dz [Z L T-1 ~> m2 s-1].

  • v0xdz :: [in] The initial meridional velocity times dz [Z L T-1 ~> m2 s-1].

  • t0xdz :: [in] The initial temperature times dz [degC Z ~> degC m].

  • s0xdz :: [in] The initial salinity times dz [ppt Z ~> ppt m].

  • kappa_avg :: [out] The time-weighted average of kappa [Z2 T-1 ~> m2 s-1].

  • 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

  • i_ld2_1d :: [out] The inverse of the squared mixing length [Z-2 ~> m-2].

  • dz_int_1d :: [out] The extent of a finite-volume space surrounding an interface,

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, u, v, T, Sal, GV, US, N2, S2, ks_int, ke_int, vel_underflow)

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, [Z2 T-1 ~> m2 s-1].

  • 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 [degC].

  • s0 :: [in] The initial salinity [ppt].

  • dz :: [in] The grid spacing of layers [Z ~> m].

  • i_dz_int :: [in] The inverse of the layer’s thicknesses [Z-1 ~> m-1].

  • dbuoy_dt :: [in] The partial derivative of buoyancy with temperature [Z T-2 degC-1 ~> m s-2 degC-1].

  • dbuoy_ds :: [in] The partial derivative of buoyancy with salinity [Z T-2 ppt-1 ~> m s-2 ppt-1].

  • dt :: [in] The time step [T ~> s].

  • 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 [degC].

  • sal :: [inout] The salinity after dt [ppt].

  • gv :: [in] The ocean’s vertical grid structure.

  • us :: [in] A dimensional unit scaling type

  • n2 :: [inout] The buoyancy frequency squared at interfaces [T-2 ~> s-2].

  • s2 :: [inout] The squared shear at interfaces [T-2 ~> s-2].

  • ks_int :: [in] The topmost k-index with a non-zero diffusivity.

  • ke_int :: [in] The bottommost k-index with a non-zero diffusivity.

  • vel_underflow :: [in] If present and true, any velocities that are smaller in magnitude than this value are set to 0 [L T-1 ~> m s-1].

Called from

kappa_shear_column

subroutine mom_kappa_shear/find_kappa_tke(N2, S2, kappa_in, Idz, dz_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 [Z2 T-1 ~> m2 s-1].

  • dz_int :: [in] The thicknesses associated with interfaces [Z-1 ~> m-1].

  • i_l2_bdry :: [in] The inverse of the squared distance to boundaries [Z-2 ~> m-2].

  • 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 [T ~> s].

  • tke :: [out] The turbulent kinetic energy per unit mass at interfaces [Z2 T-2 ~> m2 s-2].

  • kappa :: [out] The diapycnal diffusivity at interfaces [Z2 T-1 ~> m2 s-1].

  • 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