mom_set_visc module reference

Calculates various values related to the bottom boundary layer, such as the viscosity and thickness of the BBL (set_viscous_BBL).

More…

Data Types

set_visc_cs

Control structure for MOM_set_visc.

Functions/Subroutines

set_viscous_bbl()

Calculates the thickness of the bottom boundary layer and the viscosity within that layer.

set_v_at_u()

This subroutine finds a thickness-weighted value of v at the u-points.

set_u_at_v()

This subroutine finds a thickness-weighted value of u at the v-points.

set_viscous_ml()

Calculates the thickness of the surface boundary layer for applying an elevated viscosity.

set_visc_register_restarts()

Register any fields associated with the vertvisc_type.

set_visc_init()

Initializes the MOM_set_visc control structure.

set_visc_end()

This subroutine dellocates any memory in the set_visc control structure.

Detailed Description

This would also be the module in which other viscous quantities that are flow-independent might be set. This information is transmitted to other modules via a vertvisc type structure.

The same code is used for the two velocity components, by indirectly referencing the velocities and defining a handful of direction-specific defined variables.

Type Documentation

type mom_set_visc/set_visc_cs

Control structure for MOM_set_visc.

Type fields

  • % id_bbl_thick_u [integer] :: Diagnostics handles.

  • % id_kv_bbl_u [integer] :: Diagnostics handles.

  • % id_bbl_u [integer] :: Diagnostics handles.

  • % id_bbl_thick_v [integer] :: Diagnostics handles.

  • % id_kv_bbl_v [integer] :: Diagnostics handles.

  • % id_bbl_v [integer] :: Diagnostics handles.

  • % id_ray_u [integer] :: Diagnostics handles.

  • % id_ray_v [integer] :: Diagnostics handles.

  • % id_nkml_visc_u [integer] :: Diagnostics handles.

  • % id_nkml_visc_v [integer] :: Diagnostics handles.

  • % hbbl [real] :: The static bottom boundary layer thickness [H ~> m or kg m-2]. Runtime parameter

  • % cdrag [real] :: The quadratic drag coefficient. Runtime parameter

  • % c_smag [real] :: The Laplacian Smagorinsky coefficient for calculating the drag in channels.

  • % drag_bg_vel [real] :: An assumed unresolved background velocity for calculating the bottom drag [L T-1 ~> m s-1]. Runtime parameter

  • % bbl_thick_min [real] :: The minimum bottom boundary layer thickness [H ~> m or kg m-2]. This might be Kv / (cdrag * drag_bg_vel) to give Kv as the minimum near-bottom viscosity.

  • % htbl_shelf [real] :: A nominal thickness of the surface boundary layer for use in calculating the near-surface velocity [H ~> m or kg m-2].

  • % htbl_shelf_min [real] :: The minimum surface boundary layer thickness [H ~> m or kg m-2].

  • % kv_bbl_min [real] :: The minimum viscosity in the bottom boundary layer [Z2 T-1 ~> m2 s-1].

  • % kv_tbl_min [real] :: The minimum viscosity in the top boundary layer [Z2 T-1 ~> m2 s-1].

  • % bottomdraglaw [logical] :: If true, the bottom stress is calculated with a drag law c_drag*|u|*u. The velocity magnitude may be an assumed value or it may be based on the actual velocity in the bottommost

  • % bbl_use_eos [logical] :: If true, use the equation of state in determining the properties of the bottom boundary layer.

  • % linear_drag [logical] :: If true, the drag law is cdrag*

  • % channel_drag [logical] :: If true, the drag is exerted directly on each layer according to what fraction of the bottom they overlie.

  • % correct_bbl_bounds [logical] :: If true, uses the correct bounds on the BBL thickness and viscosity so that the bottom layer feels the intended drag.

  • % rino_mix [logical] :: If true, use Richardson number dependent mixing.

  • % dynamic_viscous_ml [logical] :: If true, use a bulk Richardson number criterion to determine the mixed layer thickness for viscosity.

  • % bulk_ri_ml [real] :: The bulk mixed layer used to determine the thickness of the viscous mixed layer. Nondim.

  • % omega [real] :: The Earth’s rotation rate [T-1 ~> s-1].

  • % ustar_min [real] :: A minimum value of ustar to avoid numerical problems [Z T-1 ~> m s-1]. If the value is small enough, this should not affect the solution.

  • % tke_decay [real] :: The ratio of the natural Ekman depth to the TKE decay scale, nondimensional.

  • % omega_frac [real] :: When setting the decay scale for turbulence, use this fraction of the absolute rotation rate blended with the local value of f, as sqrt((1-of)*f^2 + of*4*omega^2).

  • % answers_2018 [logical] :: If true, use the order of arithmetic and expressions that recover the answers from the end of 2018. Otherwise, use updated and more robust forms of the same expressions.

  • % debug [logical] :: If true, write verbose checksums for debugging purposes.

  • % bbl_use_tidal_bg [logical] :: If true, use a tidal background amplitude for the bottom velocity when computing the bottom stress.

  • % inputdir [character (len=200)] :: The directory for input files.

  • % obc [type(ocean_obc_type),pointer] :: Open boundaries control structure.

  • % diag [type(diag_ctrl),pointer] :: A structure that is used to regulate the timing of diagnostic output.

  • % tideamp [real(:,:),allocatable] :: RMS tidal amplitude at h points [Z T-1 ~> m s-1].

  • % bbl_u [real(:,:),allocatable] :: BBL mean U current [L T-1 ~> m s-1].

  • % bbl_v [real(:,:),allocatable] :: BBL mean V current [L T-1 ~> m s-1].

Function/Subroutine Documentation

subroutine mom_set_visc/set_viscous_bbl(u, v, h, tv, visc, G, GV, US, CS, symmetrize)

Calculates the thickness of the bottom boundary layer and the viscosity within that layer.

A drag law is used, either linearized about an assumed bottom velocity or using the actual near-bottom velocities combined with an assumed unresolved velocity. The bottom boundary layer thickness is limited by a combination of stratification and rotation, as in the paper of Killworth and Edwards, JPO 1999. It is not necessary to calculate the thickness and viscosity every time step; instead previous values may be used.

System Message: SEVERE/4 (docstring of set_viscous_bbl, line 10)

Unexpected section title.

Viscous Bottom Boundary Layer
=============================

If set_visc_cs.bottomdraglaw is True then a bottom boundary layer viscosity and thickness are calculated so that the bottom stress is is True then a bottom boundary layer viscosity and thickness are calculated so that the bottom stress is

\[\mathbf{\tau}_b = C_d | U_{bbl} | \mathbf{u}_{bbl}\]

If set_visc_cs.bottomdraglaw is True then the term is True then the term \(|U_{bbl}|\) is set equal to the value in set_visc_cs.drag_bg_vel so that so that \(C_d |U_{bbl}|\) becomes a Rayleigh bottom drag. Otherwise \(|U_{bbl}|\) is found by averaging the flow over the bottom set_visc_cs.hbbl of the model, adding the amplitude of tides of the model, adding the amplitude of tides set_visc_cs.tideamp and a constant and a constant set_visc_cs.drag_bg_vel. For these calculations the vertical grid at the velocity component locations is found by . For these calculations the vertical grid at the velocity component locations is found by

\[\begin{split}\begin{array}{ll} \frac{2 h^- h^+}{h^- + h^+} & u \left( h^+ - h^-\right) >= 0 \\ \frac{1}{2} \left( h^- + h^+ \right) & u \left( h^+ - h^-\right) < 0 \end{array}\end{split}\]

which biases towards the thin cell if the thin cell is upwind. Biasing the grid toward thin upwind cells helps increase the effect of viscosity and inhibits flow out of these thin cells.

After diagnosing \(|U_{bbl}|\) over a fixed depth an active viscous boundary layer thickness is found using the ideas of Killworth and Edwards, 1999 (hereafter KW99). KW99 solve the equation

\[\left( \frac{h_{bbl}}{h_f} \right)^2 + \frac{h_{bbl}}{h_N} = 1\]

for the boundary layer depth \(h_{bbl}\) . Here

\[h_f = \frac{C_n u_*}{f}\]

is the rotation controlled boundary layer depth in the absence of stratification. \(u_*\) is the surface friction speed given by

\[u_*^2 = C_d |U_{bbl}|^2\]

and is a function of near bottom model flow.

\[h_N = \frac{C_i u_*}{N} = \frac{ (C_i u_* )^2 }{g^\prime}\]

is the stratification controlled boundary layer depth. The non-dimensional parameters \(C_n=0.5\) and \(C_i=20\) are suggested by Zilitinkevich and Mironov, 1996.

If a Richardson number dependent mixing scheme is being used, as indicated by set_visc_cs.rino_mix, then the boundary layer thickness is bounded to be no larger than a half of , then the boundary layer thickness is bounded to be no larger than a half of set_visc_cs.hbbl ..

Todo

Channel drag needs to be explained

A BBL viscosity is calculated so that the no-slip boundary condition in the vertical viscosity solver implies the stress \(\mathbf{\tau}_b\) .

System Message: SEVERE/4 (docstring of set_viscous_bbl, line 56)

Unexpected section title.

References
----------
Parameters

  • g :: [inout] The ocean’s grid structure.

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

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

  • u :: [in] The zonal velocity [L T-1 ~> m s-1].

  • v :: [in] The 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..

  • visc :: [inout] A structure containing vertical viscosities and related fields.

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

  • symmetrize :: [in] If present and true, do extra calculations of those values in visc that would be calculated with symmetric memory.

Call to

mom_error_handler::mom_error set_u_at_v set_v_at_u

function mom_set_visc/set_v_at_u(v, h, G, i, j, k, mask2dCv, OBC) [real]

This subroutine finds a thickness-weighted value of v at the u-points.

Parameters

  • g :: [in] The ocean’s grid structure

  • v :: [in] The meridional velocity [L T-1 ~> m s-1]

  • h :: [in] Layer thicknesses [H ~> m or kg m-2]

  • i :: [in] The i-index of the u-location to work on.

  • j :: [in] The j-index of the u-location to work on.

  • k :: [in] The k-index of the u-location to work on.

  • mask2dcv :: [in] A multiplicative mask of the v-points

  • obc :: A pointer to an open boundary condition structure

Return

undefined :: The return value of v at u points points in the same units as u, i.e. [L T-1 ~> m s-1] or other units.

Called from

set_viscous_bbl set_viscous_ml

function mom_set_visc/set_u_at_v(u, h, G, i, j, k, mask2dCu, OBC) [real]

This subroutine finds a thickness-weighted value of u at the v-points.

Parameters

  • g :: [in] The ocean’s grid structure

  • u :: [in] The zonal velocity [L T-1 ~> m s-1] or other units.

  • h :: [in] Layer thicknesses [H ~> m or kg m-2]

  • i :: [in] The i-index of the u-location to work on.

  • j :: [in] The j-index of the u-location to work on.

  • k :: [in] The k-index of the u-location to work on.

  • mask2dcu :: [in] A multiplicative mask of the u-points

  • obc :: A pointer to an open boundary condition structure

Return

undefined :: The return value of u at v points in the same units as u, i.e. [L T-1 ~> m s-1] or other units.

Called from

set_viscous_bbl set_viscous_ml

subroutine mom_set_visc/set_viscous_ml(u, v, h, tv, forces, visc, dt, G, GV, US, CS, symmetrize)

Calculates the thickness of the surface boundary layer for applying an elevated viscosity.

A bulk Richardson criterion or the thickness of the topmost NKML layers (with a bulk mixed layer) are currently used. The thicknesses are given in terms of fractional layers, so that this thickness will move as the thickness of the topmost layers change.

Parameters

  • g :: [inout] The ocean’s grid structure.

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

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

  • u :: [in] The zonal velocity [L T-1 ~> m s-1].

  • v :: [in] The 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.

  • forces :: [in] A structure with the driving mechanical forces

  • visc :: [inout] A structure containing vertical viscosities and related fields.

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

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

  • symmetrize :: [in] If present and true, do extra calculations of those values in visc that would be calculated with symmetric memory.

Call to

mom_error_handler::mom_error set_u_at_v set_v_at_u

Called from

mom_dynamics_split_rk2::step_mom_dyn_split_rk2 mom_dynamics_unsplit::step_mom_dyn_unsplit mom_dynamics_unsplit_rk2::step_mom_dyn_unsplit_rk2

subroutine mom_set_visc/set_visc_register_restarts(HI, GV, param_file, visc, restart_CS)

Register any fields associated with the vertvisc_type.

Parameters

  • hi :: [in] A horizontal index type structure.

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

  • param_file :: [in] A structure to parse for run-time parameters.

  • visc :: [inout] A structure containing vertical viscosities and related fields. Allocated here.

  • restart_cs :: A pointer to the restart control structure.

Call to

mom_cvmix_conv::cvmix_conv_is_used mom_cvmix_shear::cvmix_shear_is_used mom_kappa_shear::kappa_shear_at_vertex mom_kappa_shear::kappa_shear_is_used

subroutine mom_set_visc/set_visc_init(Time, G, GV, US, param_file, diag, visc, CS, restart_CS, OBC)

Initializes the MOM_set_visc control structure.

Parameters

  • time :: [in] The current model time.

  • g :: [inout] 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.

  • visc :: [inout] A structure containing vertical viscosities and related fields. Allocated here.

  • cs :: A pointer that is set to point to the control structure for this module

  • restart_cs :: A pointer to the restart control structure.

  • obc :: A pointer to an open boundary condition structure

Call to

mom_cvmix_ddiff::cvmix_ddiff_is_used mom_kappa_shear::kappa_shear_at_vertex mom_kappa_shear::kappa_shear_is_used mom_error_handler::mom_error mom_restart::register_restart_field_as_obsolete

subroutine mom_set_visc/set_visc_end(visc, CS)

This subroutine dellocates any memory in the set_visc control structure.

Parameters

  • visc :: [inout] A structure containing vertical viscosities and related fields. Elements are deallocated here.

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