mom_thickness_diffuse module reference

Isopycnal height diffusion (or Gent McWilliams diffusion)

Data Types

thickness_diffuse_cs

Control structure for thickness_diffuse.

Functions/Subroutines

`thickness_diffuse()`	Calculates isopycnal height diffusion coefficients and applies isopycnal height diffusion by modifying to the 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_interface_kh()`	Add a diffusivity that acts on the isopycnal heights, regardless of the densities.
`add_detangling_kh()`	Modifies isopycnal height diffusivities to untangle layer structures.
`thickness_diffuse_init()`	Initialize the isopycnal height diffusion module and its control structure.
`thickness_diffuse_get_kh()`	Copies KH_u_GME and KH_v_GME from private type into arrays provided as arguments.
`thickness_diffuse_end()`	Deallocate the thickness_diffus3 control structure.

Detailed Description

Isopycnal height diffusion (aka Gent-McWilliams)

Isopycnal height 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 isopycnal height 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^4 + M^4}}$ is bounded between $-1$ and $1$ and does not change sign if $N^2<0$.

Optionally, the method of [22], 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 buoyancy 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 buoyancy 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 buoyancy frequency prescribed by [83].

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

Visbeck, 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_diffuse.

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.
% initialized :: logical True if this control structure has been initialized.
% khth :: real Background isopycnal 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 isopycnal height diffusion [nondim].
% 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.
% kh_eta_bg :: real Background isopycnal height diffusivity [L2 T-1 ~> m2 s-1].
% kh_eta_vel :: real Velocity scale that is multiplied by the grid spacing to give the isopycnal height diffusivity [L T-1 ~> m s-1].
% slope_max :: real Slopes steeper than slope_max are limited in some way [Z L-1 ~> nondim].
% kappa_smooth :: real Vertical diffusivity used to interpolate more sensible values of T & S into thin layers [H Z T-1 ~> m2 s-1 or kg m-1 s-1].
% thickness_diffuse :: logical If true, interfaces heights are diffused.
% full_depth_khth_min :: logical If true, KHTH_MIN is enforced throughout the whole water column. Otherwise, KHTH_MIN is only enforced at the surface. This parameter is only available when KHTH_USE_EBT_STRUCT=True and KHTH_MIN>0.
% 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 squared buoyancy frequency in the Ferrari et al., 2010, streamfunction formulation divided by aspect ratio rescaling factors [L2 Z-2 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 isopycnal height diffusion [nondim].
% meke_geometric_epsilon :: real Minimum Eady growth rate for the GEOMETRIC thickness diffusivity [T-1 ~> s-1].
% meke_geom_answer_date :: integer The vintage of the expressions in the MEKE_GEOMETRIC calculation. Values below 20190101 recover the answers from the original implementation, while higher values use expressions that satisfy rotational symmetry.
% use_kh_in_meke :: logical If true, uses the isopycnal height diffusivity calculated here to diffuse MEKE.
% meke_min_depth_diff :: real The minimum total depth over which to average the diffusivity used for MEKE [H ~> m or kg m-2]. When the total depth is less than this, the diffusivity is scaled away.
% 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 for MEKE.
% meke_src_answer_date :: integer The vintage of the expressions in the GM energy conversion calculation when MEKE_GM_SRC_ALT is true. Values below 20240601 recover the answers from the original implementation, while higher values use expressions that satisfy rotational symmetry.
% meke_src_slope_bug :: logical If true, use a bug that limits the positive values, but not the negative values, of the slopes used when MEKE_GM_SRC_ALT is true. When this is true, it breaks rotational symmetry.
% 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].
% read_khth :: logical If true, read a file containing the spatially varying horizontal isopycnal height diffusivity.
% use_stanley_gm :: logical If true, also use the Stanley parameterization in MOM_thickness_diffuse.
% diag :: type(diag_ctrl), pointer structure used to regulate timing of diagnostics
% gmwork :: real, dimension(:,:), allocatable Work by isopycnal height diffusion [R Z L2 T-3 ~> W m-2].
% diagslopex :: real, dimension(:,:,:), allocatable Diagnostic: zonal neutral slope [Z L-1 ~> nondim].
% diagslopey :: real, dimension(:,:,:), allocatable Diagnostic: zonal neutral slope [Z L-1 ~> nondim].
% kh_eta_u :: real, dimension(:,:), allocatable Isopycnal height diffusivities at u points [L2 T-1 ~> m2 s-1].
% kh_eta_v :: real, dimension(:,:), allocatable Isopycnal height diffusivities in v points [L2 T-1 ~> m2 s-1].
% kh_u_gme :: real, dimension(:,:,:), allocatable Isopycnal height diffusivities in u-columns [L2 T-1 ~> m2 s-1].
% kh_v_gme :: real, dimension(:,:,:), allocatable Isopycnal height diffusivities in v-columns [L2 T-1 ~> m2 s-1].
% khth2d :: real, dimension(:,:), allocatable 2D isopycnal height diffusivity at h-points [L2 T-1 ~> m2 s-1]

[source]

Function/Subroutine Documentation

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

Calculates isopycnal height diffusion coefficients and applies isopycnal height diffusion by modifying to the 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 :: h [inout] Layer thickness [H ~> m or kg m-2]
uhtr :: uhtr [inout] Accumulated zonal mass flux [L2 H ~> m3 or kg]
vhtr :: vhtr [inout] Accumulated meridional mass flux [L2 H ~> m3 or kg]
tv :: tv [in] Thermodynamics structure
dt :: dt [in] Time increment [T ~> s]
meke :: [inout] MEKE fields
varmix :: [in] Variable mixing coefficients
cdp :: [inout] Diagnostics for the continuity equation
cs :: [inout] Control structure for thickness_diffuse
stoch :: [inout] Stochastic control structure

Call to:

add_detangling_kh add_interface_kh mom_diag_mediator::diag_update_remap_grids mom_error_handler::mom_error thickness_diffuse_full

[source]

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, STOCH, VarMix)

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 :: h [in] Layer thickness [H ~> m or kg m-2]
e :: e [in] Interface positions [Z ~> m]
kh_u :: [in] Isopycnal height diffusivity at u points [L2 T-1 ~> m2 s-1]
kh_v :: [in] Isopycnal height diffusivity at v points [L2 T-1 ~> m2 s-1]
tv :: 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 :: cg1 Wave speed [L T-1 ~> m s-1]
dt :: dt [in] Time increment [T ~> s]
meke :: [inout] MEKE fields
cs :: [inout] Control structure for thickness_diffuse
int_slope_u :: 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 :: 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 :: slope_x [in] Isopyc. slope at u [Z L-1 ~> nondim]
slope_y :: slope_y [in] Isopyc. slope at v [Z L-1 ~> nondim]
stoch :: [inout] Stochastic control structure
varmix :: [in] Variable mixing coefficents

Call to:

mom_error_handler::mom_error streamfn_solver mom_isopycnal_slopes::vert_fill_ts

Called from:

thickness_diffuse

[source]

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

Tridiagonal solver for streamfunction at interfaces.

Parameters:

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

Called from:

thickness_diffuse_full

[source]

subroutine mom_thickness_diffuse/add_interface_kh(G, GV, US, CS, Kh_u, Kh_v, Kh_u_CFL, Kh_v_CFL, int_slope_u, int_slope_v)

Add a diffusivity that acts on the isopycnal heights, regardless of the densities.

Parameters:

g :: [in] Ocean grid structure
gv :: [in] Vertical grid structure
us :: [in] A dimensional unit scaling type
cs :: [in] Control structure for thickness_diffuse
kh_u :: [inout] Isopycnal height diffusivity at u points [L2 T-1 ~> m2 s-1]
kh_v :: [inout] Isopycnal height diffusivity at v points [L2 T-1 ~> m2 s-1]
kh_u_cfl :: [in] Maximum stable isopycnal height diffusivity at u points [L2 T-1 ~> m2 s-1]
kh_v_cfl :: [in] Maximum stable isopycnal height diffusivity at v points [L2 T-1 ~> m2 s-1]
int_slope_u :: 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 [nondim].
int_slope_v :: 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 [nondim].

Called from:

thickness_diffuse

[source]

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 isopycnal height diffusivities to untangle layer structures.

Parameters:

g :: [in] Ocean grid structure
gv :: [in] Vertical grid structure
us :: [in] A dimensional unit scaling type
h :: h [in] Layer thickness [H ~> m or kg m-2]
e :: e [in] Interface positions [Z ~> m]
kh_u :: [inout] Isopycnal height diffusivity at u points [L2 T-1 ~> m2 s-1]
kh_v :: [inout] Isopycnal height diffusivity at v points [L2 T-1 ~> m2 s-1]
kh_u_cfl :: [in] Maximum stable isopycnal height diffusivity at u points [L2 T-1 ~> m2 s-1]
kh_v_cfl :: [in] Maximum stable isopycnal height diffusivity at v points [L2 T-1 ~> m2 s-1]
tv :: tv [in] Thermodynamics structure
dt :: dt [in] Time increment [T ~> s]
cs :: [in] Control structure for thickness_diffuse
int_slope_u :: 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 [nondim].
int_slope_v :: 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 [nondim].

Called from:

thickness_diffuse

[source]

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

Initialize the isopycnal height diffusion module and its control 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 :: param_file [in] Parameter file handles
diag :: diag [inout] Diagnostics control structure
cdp :: [inout] Continuity equation diagnostics
cs :: [inout] Control structure for thickness_diffuse

Call to:

mom_error_handler::mom_error

[source]

subroutine mom_thickness_diffuse/thickness_diffuse_get_kh(CS, KH_u_GME, KH_v_GME, G, GV)

Copies KH_u_GME and KH_v_GME from private type into arrays provided as arguments.

Parameters:

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

Called from:

mom_hor_visc::horizontal_viscosity

[source]

subroutine mom_thickness_diffuse/thickness_diffuse_end(CS, CDp)

Deallocate the thickness_diffus3 control structure.

Parameters:

cs :: [inout] Control structure for thickness_diffuse
cdp :: [inout] Continuity diagnostic control structure

Called from:

mom::mom_end

[source]