namespace mom_vert_friction

Overview

Implements vertical viscosity (vertvisc) More…

namespace mom_vert_friction {

// global functions

subroutine, public vertvisc(
    u u,
    v v,
    h h,
    forces forces,
    visc visc,
    dt dt,
    OBC OBC,
    ADp ADp,
    CDp CDp,
    G G,
    GV GV,
    US US,
    CS CS,
    taux_bot taux_bot,
    tauy_bot tauy_bot,
    Waves Waves
    );

subroutine, public vertvisc_remnant(
    visc visc,
    visc_rem_u visc_rem_u,
    visc_rem_v visc_rem_v,
    dt dt,
    G G,
    GV GV,
    US US,
    CS CS
    );

subroutine, public vertvisc_coef(
    u u,
    v v,
    h h,
    forces forces,
    visc visc,
    dt dt,
    G G,
    GV GV,
    US US,
    CS CS,
    OBC OBC
    );

subroutine, public vertvisc_limit_vel(
    u u,
    v v,
    h h,
    ADp ADp,
    CDp CDp,
    forces forces,
    visc visc,
    dt dt,
    G G,
    GV GV,
    US US,
    CS CS
    );

subroutine, public vertvisc_init(
    MIS MIS,
    Time Time,
    G G,
    GV GV,
    US US,
    param_file param_file,
    diag diag,
    ADp ADp,
    dirs dirs,
    ntrunc ntrunc,
    CS CS
    );

subroutine, public updatecfltruncationvalue(Time Time, CS CS, activate activate);
subroutine, public vertvisc_end(CS CS);

} // namespace mom_vert_friction

Detailed Documentation

Implements vertical viscosity (vertvisc)

Robert Hallberg

April 1994 - October 2006

The vertical diffusion of momentum is fully implicit. This is necessary to allow for vanishingly small layers. The coupling is based on the distance between the centers of adjacent layers, except where a layer is close to the bottom compared with a bottom boundary layer thickness when a bottom drag law is used. A stress top b.c. and a no slip bottom b.c. are used. There is no limit on the time step for vertvisc.

Near the bottom, the horizontal thickness interpolation scheme changes to an upwind biased estimate to control the effect of spurious Montgomery potential gradients at the bottom where nearly massless layers layers ride over the topography. Within a few boundary layer depths of the bottom, the harmonic mean thickness (i.e. (2 h+ h-) / (h+ + h-) ) is used if the velocity is from the thinner side and the arithmetic mean thickness (i.e. (h+ + h-)/2) is used if the velocity is from the thicker side. Both of these thickness estimates are second order accurate. Above this the arithmetic mean thickness is used.

In addition, vertvisc truncates any velocity component that exceeds maxvel to truncvel. This basically keeps instabilities spatially localized. The number of times the velocity is truncated is reported each time the energies are saved, and if exceeds CSMaxtrunc the model will stop itself and change the time to a large value. This has proven very useful in (1) diagnosing model failures and (2) letting the model settle down to a meaningful integration from a poorly specified initial condition.

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

Macros written all in capital letters are defined in MOM_memory.h.

A small fragment of the grid is shown below: j+1 x ^ x ^ x At x: q

j+1 > o > o > At ^: v, frhatv, tauy j x ^ x ^ x At >: u, frhatu, taux j > o > o > At o: h j-1 x ^ x ^ x

i-1 i i+1 At x & ^:

i i+1 At > & o:

The boundaries always run through q grid points (x).

Global Functions

subroutine, public vertvisc(
    u u,
    v v,
    h h,
    forces forces,
    visc visc,
    dt dt,
    OBC OBC,
    ADp ADp,
    CDp CDp,
    G G,
    GV GV,
    US US,
    CS CS,
    taux_bot taux_bot,
    tauy_bot tauy_bot,
    Waves Waves
    )

Perform a fully implicit vertical diffusion of momentum. Stress top and bottom boundary conditions are used.

This is solving the tridiagonal system

\[\left(h_k + a_{k + 1/2} + a_{k - 1/2} + r_k\right) u_k^{n+1} = h_k u_k^n + a_{k + 1/2} u_{k+1}^{n+1} + a_{k - 1/2} u_{k-1}^{n+1}\]

where \(a_{k + 1/2} = \Delta t \nu_{k + 1/2} / h_{k + 1/2}\) is the interfacial coupling thickness per time step, encompassing background viscosity as well as contributions from enhanced mixed and bottom layer viscosities. $r_k$ is a Rayleight drag term due to channel drag. There is an additional stress term on the right-hand side if DIRECT_STRESS is true, applied to the surface layer.

Parameters:

g	Ocean grid structure
gv	Ocean vertical grid structure
us	A dimensional unit scaling type
u	Zonal velocity [L T-1 ~> m s-1]
v	Meridional velocity [L T-1 ~> m s-1]
h	Layer thickness [H ~> m or kg m-2]
forces	A structure with the driving mechanical forces
visc	Viscosities and bottom drag
dt	Time increment [s]
obc	Open boundary condition structure
adp	Accelerations in the momentum equations for diagnostics
cdp	Continuity equation terms
cs	Vertical viscosity control structure
taux_bot	Zonal bottom stress from ocean to
tauy_bot	Meridional bottom stress from ocean to
waves	Container for wave/Stokes information

subroutine, public vertvisc_remnant(
    visc visc,
    visc_rem_u visc_rem_u,
    visc_rem_v visc_rem_v,
    dt dt,
    G G,
    GV GV,
    US US,
    CS CS
    )

Calculate the fraction of momentum originally in a layer that remains after a time-step of viscosity, and the fraction of a time-step’s worth of barotropic acceleration that a layer experiences after viscosity is applied.

Parameters:

g	Ocean grid structure
gv	Ocean vertical grid structure
visc	Viscosities and bottom drag
visc_rem_u	Fraction of a time-step’s worth of a
visc_rem_v	Fraction of a time-step’s worth of a
dt	Time increment [s]
us	A dimensional unit scaling type
cs	Vertical viscosity control structure

subroutine, public vertvisc_coef(
    u u,
    v v,
    h h,
    forces forces,
    visc visc,
    dt dt,
    G G,
    GV GV,
    US US,
    CS CS,
    OBC OBC
    )

Calculate the coupling coefficients (CSa_u and CSa_v) and effective layer thicknesses (CSh_u and CSh_v) for later use in the applying the implicit vertical viscosity via vertvisc().

Parameters:

g	Ocean grid structure
gv	Ocean vertical grid structure
us	A dimensional unit scaling type
u	Zonal velocity [L T-1 ~> m s-1]
v	Meridional velocity [L T-1 ~> m s-1]
h	Layer thickness [H ~> m or kg m-2]
forces	A structure with the driving mechanical forces
visc	Viscosities and bottom drag
dt	Time increment [s]
cs	Vertical viscosity control structure
obc	Open boundary condition structure

subroutine, public vertvisc_limit_vel(
    u u,
    v v,
    h h,
    ADp ADp,
    CDp CDp,
    forces forces,
    visc visc,
    dt dt,
    G G,
    GV GV,
    US US,
    CS CS
    )

Velocity components which exceed a threshold for physically reasonable values are truncated. Optionally, any column with excessive velocities may be sent to a diagnostic reporting subroutine.

Parameters:

g	Ocean grid structure
gv	Ocean vertical grid structure
us	A dimensional unit scaling type
u	Zonal velocity [L T-1 ~> m s-1]
v	Meridional velocity [L T-1 ~> m s-1]
h	Layer thickness [H ~> m or kg m-2]
adp	Acceleration diagnostic pointers
cdp	Continuity diagnostic pointers
forces	A structure with the driving mechanical forces
visc	Viscosities and bottom drag
dt	Time increment [s]
cs	Vertical viscosity control structure

subroutine, public vertvisc_init(
    MIS MIS,
    Time Time,
    G G,
    GV GV,
    US US,
    param_file param_file,
    diag diag,
    ADp ADp,
    dirs dirs,
    ntrunc ntrunc,
    CS CS
    )

Initialize the vertical friction module.

Parameters:

mis	The “MOM Internal State”, a set of pointers
time	Current model time
g	Ocean grid structure
gv	Ocean vertical grid structure
us	A dimensional unit scaling type
param_file	File to parse for parameters
diag	Diagnostic control structure
adp	Acceleration diagnostic pointers
dirs	Relevant directory paths
ntrunc	Number of velocity truncations
cs	Vertical viscosity control structure

subroutine, public updatecfltruncationvalue(Time Time, CS CS, activate activate)

Update the CFL truncation value as a function of time. If called with the optional argument activate=.true., record the value of Time as the beginning of the ramp period.

Parameters:

time	Current model time
cs	Vertical viscosity control structure
activate	Specifiy whether to record the value of Time as the beginning of the ramp period

subroutine, public vertvisc_end(CS CS)

Clean up and deallocate the vertical friction module.

Parameters:

cs	Vertical viscosity control structure that will be deallocated in this subroutine.