mom_thickness_diffuse module reference¶

Thickness diffusion (or Gent McWilliams)

Data Types¶

thickness_diffuse_cs

Control structure for thickness diffusion.

Functions/Subroutines¶

`thickness_diffuse()`	Calculates thickness diffusion coefficients and applies thickness diffusion to layer thicknesses, h.
`thickness_diffuse_full()`	Calculates parameterized layer transports for use in the continuity equation.
`streamfn_solver()`	Tridiagonal solver for streamfunction at interfaces.
`add_detangling_kh()`	Modifies thickness diffusivities to untangle layer structures.
`thickness_diffuse_init()`	Initialize the thickness diffusion module/structure.
`thickness_diffuse_get_kh()`	Copies ubtav and vbtav from private type into arrays.
`thickness_diffuse_end()`	Deallocate the thickness diffusion control structure.

Detailed Description¶

Thickness diffusion (aka Gent-McWilliams)¶

Thickness diffusion is implemented via along-layer mass fluxes

\[h^\dagger \leftarrow h^n - \Delta t \nabla \cdot ( \vec{uh}^* )\]

where the mass fluxes are cast as the difference in vector streamfunction

\[\vec{uh}^* = \delta_k \vec{\psi} .\]

The GM implementation of thickness diffusion made the streamfunction proportional to the potential density slope

\[\vec{\psi} = - \kappa_h \frac{\nabla_z \rho}{\partial_z \rho} = \frac{g\kappa_h}{\rho_o} \frac{\nabla \rho}{N^2} = \kappa_h \frac{M^2}{N^2}\]

but for robustness the scheme is implemented as

\[\vec{\psi} = \kappa_h \frac{M^2}{\sqrt{N^4 + M^4}}\]

since the quantity $\frac{M^2}{\sqrt{N^2 + M^2}}$ is bounded between $-1$ and $1$ and does not change sign if $N^2<0$ .

Optionally, the method of Ferrari et al, 2010, can be used to obtain the streamfunction which solves the vertically elliptic equation:

\[\gamma_F \partial_z c^2 \partial_z \psi - N_*^2 \psi = ( 1 + \gamma_F ) \kappa_h N_*^2 \frac{M^2}{\sqrt{N^4+M^4}}\]

which recovers the previous streamfunction relation in the limit that $c \rightarrow 0$ . Here, $c=\max(c_{min},c_g)$ is the maximum of either $c_{min}$ and either the first baroclinic mode wave-speed or the equivalent barotropic mode wave-speed. $N_*^2 = \max(N^2,0)$ is a non-negative form of the square of the Brunt-Vaisala frequency. The parameter $\gamma_F$ is used to reduce the vertical smoothing length scale.

\[\kappa_h = \left( \kappa_o + \alpha_{s} L_{s}^2 < S N > + \alpha_{M} \kappa_{M} \right) r(\Delta x,L_d)\]

where $S$ is the isoneutral slope magnitude, $N$ is the square root of Brunt-Vaisala frequency, $\kappa_{M}$ is the diffusivity calculated by the MEKE parameterization (mom_meke() module) and module) and $r(\Delta x,L_d)$ is a function of the local resolution (ratio of grid-spacing, $\Delta x$ , to deformation radius, $L_d$ ). The length $L_s$ is provided by the mom_lateral_mixing_coeffs() module (enabled with module (enabled with USE_VARIABLE_MIXING=True and the term $<SN>$ is the vertical average slope times the Brunt-Vaisala frequency prescribed by Visbeck et al., 1996.

The result of the above expression is subsequently bounded by minimum and maximum values, including an upper diffusivity consistent with numerical stability ( $\kappa_{cfl}$ is calculated internally).

\[\kappa_h \leftarrow \min{\left( \kappa_{max}, \kappa_{cfl}, \max{\left( \kappa_{min}, \kappa_h \right)} \right)} f(c_g,z)\]

where $f(c_g,z)$ is a vertical structure function. $f(c_g,z)$ is calculated in module mom_lateral_mixing_coeffs(). If . If KHTH_USE_EBT_STRUCT=True then $f(c_g,z)$ is set to look like the equivalent barotropic modal velocity structure. Otherwise $f(c_g,z)=1$ and the diffusivity is independent of depth.

In order to calculate meaningful slopes in vanished layers, temporary copies of the thermodynamic variables are passed through a vertical smoother, function vert_fill_ts(): :

\[\begin{split}\begin{eqnarray*} \left[ 1 + \Delta t \kappa_{smth} \frac{\partial^2}{\partial_z^2} \right] \theta & \leftarrow & \theta \\ \left[ 1 + \Delta t \kappa_{smth} \frac{\partial^2}{\partial_z^2} \right] s & \leftarrow & s \end{eqnarray*}\end{split}\]

Module mom_thickness_diffuse parameters¶

Symbol	Module parameter
	`THICKNESSDIFFUSE`
$\kappa_o$	`KHTH`
$\alpha_{s}$	`KHTH_SLOPE_CFF`
$\kappa_{min}$	`KHTH_MIN`
$\kappa_{max}$	`KHTH_MAX`
	`KHTH_MAX_CFL`
$\kappa_{smth}$	`KD_SMOOTH`
$\alpha_{M}$	`MEKE_KHTH_FAC` (from `mom_meke()` module) module)
	`KHTH_USE_EBT_STRUCT` (from `mom_lateral_mixing_coeffs()` module) module)
	`KHTH_USE_FGNV_STREAMFUNCTION`
$\gamma_F$	`FGNV_FILTER_SCALE`
$c_{min}$	`FGNV_C_MIN`

References¶

Ferrari, R., S.M. Griffies, A.J.G. Nurser and G.K. Vallis, 2010: A boundary-value problem for the parameterized mesoscale eddy transport. Ocean Modelling, 32, 143-156. http://doi.org/10.1016/j.ocemod.2010.01.004

Viscbeck, M., J.C. Marshall, H. Jones, 1996: Dynamics of isolated convective regions in the ocean. J. Phys. Oceangr., 26, 1721-1734. http://dx.doi.org/10.1175/1520-0485(1996)026%3C1721:DOICRI%3E2.0.CO;2

Type Documentation¶

type mom_thickness_diffuse/thickness_diffuse_cs¶

Control structure for thickness diffusion.

Type fields

% id_uhgm [integer] :: Diagnostic identifier.
% id_vhgm [integer] :: Diagnostic identifier.
% id_gmwork [integer] :: Diagnostic identifier.
% id_kh_u [integer] :: Diagnostic identifier.
% id_kh_v [integer] :: Diagnostic identifier.
% id_kh_t [integer] :: Diagnostic identifier.
% id_kh_u1 [integer] :: Diagnostic identifier.
% id_kh_v1 [integer] :: Diagnostic identifier.
% id_kh_t1 [integer] :: Diagnostic identifier.
% id_slope_x [integer] :: Diagnostic identifier.
% id_slope_y [integer] :: Diagnostic identifier.
% id_sfn_unlim_x [integer] :: Diagnostic identifier.
% id_sfn_unlim_y [integer] :: Diagnostic identifier.
% id_sfn_x [integer] :: Diagnostic identifier.
% id_sfn_y [integer] :: Diagnostic identifier.
% khth [real] :: Background interface depth diffusivity [L2 T-1 ~> m2 s-1].
% khth_slope_cff [real] :: Slope dependence coefficient of Khth [nondim].
% max_khth_cfl [real] :: Maximum value of the diffusive CFL for thickness diffusion.
% khth_min [real] :: Minimum value of Khth [L2 T-1 ~> m2 s-1].
% khth_max [real] :: Maximum value of Khth [L2 T-1 ~> m2 s-1], or 0 for no max.
% slope_max [real] :: Slopes steeper than slope_max are limited in some way [nondim].
% kappa_smooth [real] :: Vertical diffusivity used to interpolate more sensible values of T & S into thin layers [Z2 T-1 ~> m2 s-1].
% thickness_diffuse [logical] :: If true, interfaces heights are diffused.
% use_fgnv_streamfn [logical] :: If true, use the streamfunction formulation of Ferrari et al., 2010, which effectively emphasizes graver vertical modes by smoothing in the vertical.
% fgnv_scale [real] :: A coefficient scaling the vertical smoothing term in the Ferrari et al., 2010, streamfunction formulation [nondim].
% fgnv_c_min [real] :: A minimum wave speed used in the Ferrari et al., 2010, streamfunction formulation [L T-1 ~> m s-1].
% n2_floor [real] :: A floor for Brunt-Vasaila frequency in the Ferrari et al., 2010, streamfunction formulation [T-2 ~> s-2].
% detangle_interfaces [logical] :: If true, add 3-d structured interface height diffusivities to horizontally smooth jagged layers.
% detangle_time [real] :: If detangle_interfaces is true, this is the timescale over which maximally jagged grid-scale thickness variations are suppressed [T ~> s]. This must be longer than DT, or 0 (the default) to use DT.
% nkml [integer] :: number of layers within mixed layer
% debug [logical] :: write verbose checksums for debugging purposes
% use_gme_thickness_diffuse [logical] :: If true, passes GM coefficients to MOM_hor_visc for use with GME closure.
% meke_geometric [logical] :: If true, uses the GM coefficient formulation from the GEOMETRIC framework (Marshall et al., 2012)
% meke_geometric_alpha [real] :: The nondimensional coefficient governing the efficiency of the GEOMETRIC thickness difussion [nondim].
% meke_geometric_epsilon [real] :: Minimum Eady growth rate for the GEOMETRIC thickness diffusivity [T-1 ~> s-1].
% meke_geom_answers_2018 [logical] :: If true, use expressions in the MEKE_GEOMETRIC calculation that recover the answers from the original implementation. Otherwise, use expressions that satisfy rotational symmetry.
% use_kh_in_meke [logical] :: If true, uses the thickness diffusivity calculated here to diffuse MEKE.
% gm_src_alt [logical] :: If true, use the GM energy conversion form S^2*N^2*kappa rather than the streamfunction for the GM source term.
% use_gm_work_bug [logical] :: If true, use the incorrect sign for the top-level work tendency on the top layer.
% stanley_det_coeff [real] :: The coefficient correlating SGS temperature variance with the mean temperature gradient in the deterministic part of the Stanley parameterization. Negative values disable the scheme.” [nondim].
% diag [type(diag_ctrl),pointer] :: structure used to regulate timing of diagnostics
% gmwork [real(:,:),pointer] :: Work by thickness diffusivity [R Z L2 T-3 ~> W m-2].
% diagslopex [real(:,:,:),pointer] :: Diagnostic: zonal neutral slope [nondim].
% diagslopey [real(:,:,:),pointer] :: Diagnostic: zonal neutral slope [nondim].
% kh_u_gme [real(:,:,:),pointer] :: interface height diffusivities in u-columns [L2 T-1 ~> m2 s-1]
% kh_v_gme [real(:,:,:),pointer] :: interface height diffusivities in v-columns [L2 T-1 ~> m2 s-1]

Function/Subroutine Documentation¶

subroutine mom_thickness_diffuse/thickness_diffuse(h, uhtr, vhtr, tv, dt, G, GV, US, MEKE, VarMix, CDp, CS)¶

Calculates thickness diffusion coefficients and applies thickness diffusion to layer thicknesses, h. Diffusivities are limited to ensure stability. Also returns along-layer mass fluxes used in the continuity equation.

Parameters

g :: [in] Ocean grid structure
gv :: [in] Vertical grid structure
us :: [in] A dimensional unit scaling type
h :: [inout] Layer thickness [H ~> m or kg m-2]
uhtr :: [inout] Accumulated zonal mass flux [L2 H ~> m3 or kg]
vhtr :: [inout] Accumulated meridional mass flux [L2 H ~> m3 or kg]
tv :: [in] Thermodynamics structure
dt :: [in] Time increment [T ~> s]
meke :: MEKE control structure
varmix :: Variable mixing coefficients
cdp :: [inout] Diagnostics for the continuity equation
cs :: Control structure for thickness diffusion

Call to

add_detangling_kh mom_diag_mediator::diag_update_remap_grids mom_error_handler::mom_error thickness_diffuse_full

subroutine mom_thickness_diffuse/thickness_diffuse_full(h, e, Kh_u, Kh_v, tv, uhD, vhD, cg1, dt, G, GV, US, MEKE, CS, int_slope_u, int_slope_v, slope_x, slope_y)¶

Calculates parameterized layer transports for use in the continuity equation. Fluxes are limited to give positive definite thicknesses. Called by thickness_diffuse(). .

Parameters

g :: [in] Ocean grid structure
gv :: [in] Vertical grid structure
us :: [in] A dimensional unit scaling type
h :: [in] Layer thickness [H ~> m or kg m-2]
e :: [in] Interface positions [Z ~> m]
kh_u :: [in] Thickness diffusivity on interfaces at u points [L2 T-1 ~> m2 s-1]
kh_v :: [in] Thickness diffusivity on interfaces at v points [L2 T-1 ~> m2 s-1]
tv :: [in] Thermodynamics structure
uhd :: [out] Zonal mass fluxes [H L2 T-1 ~> m3 s-1 or kg s-1]
vhd :: [out] Meridional mass fluxes [H L2 T-1 ~> m3 s-1 or kg s-1]
cg1 :: Wave speed [L T-1 ~> m s-1]
dt :: [in] Time increment [T ~> s]
meke :: MEKE control structure
cs :: Control structure for thickness diffusion
int_slope_u :: [in] Ratio that determine how much of the isopycnal slopes are taken directly from the interface slopes without consideration of density gradients [nondim].
int_slope_v :: [in] Ratio that determine how much of the isopycnal slopes are taken directly from the interface slopes without consideration of density gradients [nondim].
slope_x :: [in] Isopycnal slope at u-points
slope_y :: [in] Isopycnal slope at v-points

Call to

streamfn_solver

Called from

thickness_diffuse

subroutine mom_thickness_diffuse/streamfn_solver(nk, c2_h, hN2, sfn)¶

Tridiagonal solver for streamfunction at interfaces.

Parameters

nk :: [in] Number of layers
c2_h :: [in] Wave speed squared over thickness in layers [L2 Z-1 T-2 ~> m s-2]
hn2 :: [in] Thickness times N2 at interfaces [L2 Z-1 T-2 ~> m s-2]
sfn :: [inout] Streamfunction [Z L2 T-1 ~> m3 s-1] or arbitrary units On entry, equals diffusivity times slope. On exit, equals the streamfunction.

Called from

thickness_diffuse_full

subroutine mom_thickness_diffuse/add_detangling_kh(h, e, Kh_u, Kh_v, KH_u_CFL, KH_v_CFL, tv, dt, G, GV, US, CS, int_slope_u, int_slope_v)¶

Modifies thickness diffusivities to untangle layer structures.

Parameters

g :: [in] Ocean grid structure
gv :: [in] Vertical grid structure
us :: [in] A dimensional unit scaling type
h :: [in] Layer thickness [H ~> m or kg m-2]
e :: [in] Interface positions [Z ~> m]
kh_u :: [inout] Thickness diffusivity on interfaces at u points [L2 T-1 ~> m2 s-1]
kh_v :: [inout] Thickness diffusivity on interfaces at v points [L2 T-1 ~> m2 s-1]
kh_u_cfl :: [in] Maximum stable thickness diffusivity at u points [L2 T-1 ~> m2 s-1]
kh_v_cfl :: [in] Maximum stable thickness diffusivity at v points [L2 T-1 ~> m2 s-1]
tv :: [in] Thermodynamics structure
dt :: [in] Time increment [T ~> s]
cs :: Control structure for thickness diffusion
int_slope_u :: [inout] Ratio that determine how much of the isopycnal slopes are taken directly from the interface slopes without consideration of density gradients.
int_slope_v :: [inout] Ratio that determine how much of the isopycnal slopes are taken directly from the interface slopes without consideration of density gradients.

Called from

thickness_diffuse

subroutine mom_thickness_diffuse/thickness_diffuse_init(Time, G, GV, US, param_file, diag, CDp, CS)¶

Initialize the thickness diffusion module/structure.

Parameters

time :: [in] Current model time
g :: [in] Ocean grid structure
gv :: [in] Vertical grid structure
us :: [in] A dimensional unit scaling type
param_file :: [in] Parameter file handles
diag :: [inout] Diagnostics control structure
cdp :: [inout] Continuity equation diagnostics
cs :: Control structure for thickness diffusion

subroutine mom_thickness_diffuse/thickness_diffuse_get_kh(CS, KH_u_GME, KH_v_GME, G)¶

Copies ubtav and vbtav from private type into arrays.

Parameters

cs :: Control structure for this module
g :: [in] Grid structure
kh_u_gme :: [inout] interface height diffusivities at u-faces [L2 T-1 ~> m2 s-1]
kh_v_gme :: [inout] interface height diffusivities at v-faces [L2 T-1 ~> m2 s-1]

subroutine mom_thickness_diffuse/thickness_diffuse_end(CS)¶

Deallocate the thickness diffusion control structure.

Parameters: cs :: Control structure for thickness diffusion