mom_entrain_diffusive module reference

Diapycnal mixing and advection in isopycnal mode.

More…

Data Types

entrain_diffusive_cs

The control structure holding parametes for the MOM_entrain_diffusive module.

Functions/Subroutines

entrainment_diffusive()

This subroutine calculates ea and eb, the rates at which a layer entrains from the layers above and below.

f_to_ent()

This subroutine calculates the actual entrainments (ea and eb) and the amount of surface forcing that is applied to each layer if there is no bulk mixed layer.

set_ent_bl()

This subroutine sets the average entrainment across each of the interfaces between buffer layers within a timestep.

determine_dskb()

This subroutine determines the reference density difference between the bottommost buffer layer and the first interior after the mixing between mixed and buffer layers and mixing with the layer below.

f_kb_to_ea_kb()

Given an entrainment from below for layer kb, determine a consistent entrainment from above, such that dSkb * ea_kb = dSkbp1 * F_kb.

determine_ea_kb()

This subroutine determines the entrainment from above by the top interior layer (labeled kb elsewhere) given an entrainment by the layer below it, constrained to be within the provided bounds.

find_maxf_kb()

Maximize F = ent*ds_kb*I_dSkbp1 in the range min_ent < ent < max_ent.

entrain_diffusive_init()

This subroutine initializes the parameters and memory associated with the entrain_diffusive module.

Detailed Description

By Robert Hallberg, September 1997 - July 2000.

This file contains the subroutines that implement diapycnal mixing and advection in isopycnal layers. The main subroutine, calculate_entrainment, returns the entrainment by each layer across the interfaces above and below it. These are calculated subject to the constraints that no layers can be driven to negative thickness and that the each layer maintains its target density, using the scheme described in Hallberg (MWR 2000). There may or may not be a bulk mixed layer above the isopycnal layers. The solution is iterated until the change in the entrainment between successive iterations is less than some small tolerance.

The dual-stream entrainment scheme of MacDougall and Dewar (JPO 1997) is used for combined diapycnal advection and diffusion, modified as described in Hallberg (MWR 2000) to be solved implicitly in time. Any profile of diffusivities may be used. Diapycnal advection is fundamentally the residual of diapycnal diffusion, so the fully implicit upwind differencing scheme that is used is entirely appropriate. The downward buoyancy flux in each layer is determined from an implicit calculation based on the previously calculated flux of the layer above and an estimated flux in the layer below. This flux is subject to the following conditions: (1) the flux in the top and bottom layers are set by the boundary conditions, and (2) no layer may be driven below an Angstrom thickness. If there is a bulk mixed layer, the mixed and buffer layers are treated as Eulerian layers, whose thicknesses only change due to entrainment by the interior layers.

Type Documentation

type mom_entrain_diffusive/entrain_diffusive_cs

The control structure holding parametes for the MOM_entrain_diffusive module.

Type fields:
  • % initialized [logical] :: True if this control structure has been initialized.

  • % bulkmixedlayer [logical] :: If true, a refined bulk mixed layer is used with GVnk_rho_varies variable density mixed & buffer layers.

  • % max_ent_it [integer] :: The maximum number of iterations that may be used to calculate the diapycnal entrainment.

  • % tolerance_ent [real] :: The tolerance with which to solve for entrainment values [H ~> m or kg m-2].

  • % max_ent [real] :: A large ceiling on the maximum permitted amount of entrainment across each interface between the mixed and buffer layers within a timestep [H ~> m or kg m-2].

  • % rho_sig_off [real] :: The offset between potential density and a sigma value [R ~> kg m-3].

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

  • % id_kd [integer] :: Diagnostic ID for diffusivity.

  • % id_diff_work [integer] :: Diagnostic ID for mixing work.

Function/Subroutine Documentation

subroutine mom_entrain_diffusive/entrainment_diffusive(h, tv, fluxes, dt, G, GV, US, CS, ea, eb, kb_out, Kd_Lay, Kd_int)

This subroutine calculates ea and eb, the rates at which a layer entrains from the layers above and below. The entrainment rates are proportional to the buoyancy flux in a layer and inversely proportional to the density differences between layers. The scheme that is used here is described in detail in Hallberg, Mon. Wea. Rev. 2000.

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

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

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

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

  • fluxes :: [in] A structure of surface fluxes that may be used.

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

  • cs :: [in] The control structure returned by a previous call to entrain_diffusive_init.

  • ea :: [out] The amount of fluid entrained from the layer

  • eb :: [out] The amount of fluid entrained from the layer

  • kb_out :: [inout] The index of the lightest layer denser than

  • kd_lay :: [in] The diapycnal diffusivity of layers

  • kd_int :: [in] The diapycnal diffusivity of interfaces

Call to:

determine_dskb determine_ea_kb mom_eos::eos_domain f_kb_to_ea_kb f_to_ent find_maxf_kb mom_error_handler::mom_error set_ent_bl

subroutine mom_entrain_diffusive/f_to_ent(F, h, kb, kmb, j, G, GV, CS, dsp1_ds, eakb, Ent_bl, ea, eb)

This subroutine calculates the actual entrainments (ea and eb) and the amount of surface forcing that is applied to each layer if there is no bulk mixed layer.

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

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

  • f :: [in] The density flux through a layer within a time step divided by the density difference across the interface below the layer [H ~> m or kg m-2].

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

  • kb :: [in] The index of the lightest layer denser than the deepest buffer layer.

  • kmb :: [in] The number of mixed and buffer layers.

  • j :: [in] The meridional index upon which to work.

  • cs :: [in] This module’s control structure.

  • dsp1_ds :: [in] The ratio of coordinate variable differences across the interfaces below a layer over the difference across the interface above the layer [nondim].

  • eakb :: [in] The entrainment from above by the layer below the buffer layer [H ~> m or kg m-2].

  • ent_bl :: [in] The average entrainment upward and downward across each interface around the buffer layers [H ~> m or kg m-2].

  • ea :: [inout] The amount of fluid entrained from the layer

  • eb :: [inout] The amount of fluid entrained from the layer

Called from:

entrainment_diffusive

subroutine mom_entrain_diffusive/set_ent_bl(h, dtKd_int, tv, kb, kmb, do_i, G, GV, US, CS, j, Ent_bl, Sref, h_bl)

This subroutine sets the average entrainment across each of the interfaces between buffer layers within a timestep. It also causes thin and relatively light interior layers to be entrained by the deepest buffer layer. Also find the initial coordinate potential densities (Sref) of each layer.

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

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

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

  • dtkd_int :: [in] The diapycnal diffusivity across

  • tv :: [in] A structure containing pointers to any available thermodynamic fields. Absent fields have NULL ptrs.

  • kb :: [inout] The index of the lightest layer denser than the buffer layer or 1 if there is no buffer layer.

  • kmb :: [in] The number of mixed and buffer layers.

  • do_i :: [in] A logical variable indicating which i-points to work on.

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

  • cs :: [in] This module’s control structure.

  • j :: [in] The meridional index upon which to work.

  • ent_bl :: [out] The average entrainment upward and

  • sref :: [out] The coordinate potential density minus 1000 for each layer [R ~> kg m-3].

  • h_bl :: [out] The thickness of each layer [H ~> m or kg m-2].

Call to:

mom_eos::eos_domain

Called from:

entrainment_diffusive

subroutine mom_entrain_diffusive/determine_dskb(h_bl, Sref, Ent_bl, E_kb, is, ie, kmb, G, GV, limit, dSkb, ddSkb_dE, dSlay, ddSlay_dE, dS_anom_lim, do_i_in)

This subroutine determines the reference density difference between the bottommost buffer layer and the first interior after the mixing between mixed and buffer layers and mixing with the layer below. Within the mixed and buffer layers, entrainment from the layer above is increased when it is necessary to keep the layers from developing a negative thickness; otherwise it equals Ent_bl. At each interface, the upward and downward fluxes average out to Ent_bl, unless entrainment by the layer below is larger than twice Ent_bl. The density difference across the first interior layer may also be returned. It could also be limited to avoid negative values or values that greatly exceed the density differences across an interface. Additionally, the partial derivatives of dSkb and dSlay with E_kb could also be returned.

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

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

  • h_bl :: [in] Layer thickness [H ~> m or kg m-2]

  • sref :: [in] Reference potential density [R ~> kg m-3]

  • ent_bl :: [in] The average entrainment upward and downward across each interface around the buffer layers [H ~> m or kg m-2].

  • e_kb :: [in] The entrainment by the top interior layer [H ~> m or kg m-2].

  • is :: [in] The start of the i-index range to work on.

  • ie :: [in] The end of the i-index range to work on.

  • kmb :: [in] The number of mixed and buffer layers.

  • limit :: [in] If true, limit dSkb and dSlay to avoid negative values.

  • dskb :: [inout] The limited potential density difference across the interface between the bottommost buffer layer and the topmost interior layer. [R ~> kg m-3] dSkb > 0.

  • ddskb_de :: [inout] The partial derivative of dSkb with E [R H-1 ~> kg m-4 or m-1].

  • dslay :: [inout] The limited potential density difference across the topmost interior layer. 0 < dSkb [R ~> kg m-3]

  • ddslay_de :: [inout] The partial derivative of dSlay with E [R H-1 ~> kg m-4 or m-1].

  • ds_anom_lim :: [inout] A limiting value to use for the density anomalies below the buffer layer [R ~> kg m-3].

  • do_i_in :: [in] If present, determines which columns are worked on.

Call to:

mom_error_handler::mom_error

Called from:

determine_ea_kb entrainment_diffusive f_kb_to_ea_kb find_maxf_kb

subroutine mom_entrain_diffusive/f_kb_to_ea_kb(h_bl, Sref, Ent_bl, I_dSkbp1, F_kb, kmb, i, G, GV, CS, ea_kb, tol_in)

Given an entrainment from below for layer kb, determine a consistent entrainment from above, such that dSkb * ea_kb = dSkbp1 * F_kb. The input value of ea_kb is both the maximum value that can be obtained and the first guess of the iterations. Ideally ea_kb should be an under-estimate.

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

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

  • h_bl :: [in] Layer thickness, with the top interior

  • sref :: [in] The coordinate reference potential density,

  • ent_bl :: [in] The average entrainment upward and downward

  • i_dskbp1 :: [in] The inverse of the difference in reference potential density across the base of the uppermost interior layer [R-1 ~> m3 kg-1].

  • f_kb :: [in] The entrainment from below by the uppermost interior layer [H ~> m or kg m-2]

  • kmb :: [in] The number of mixed and buffer layers.

  • i :: [in] The i-index to work on

  • cs :: [in] This module’s control structure.

  • ea_kb :: [inout] The entrainment from above by the layer below the buffer layer (i.e. layer kb) [H ~> m or kg m-2].

  • tol_in :: [in] A tolerance for the iterative determination of the entrainment [H ~> m or kg m-2].

Call to:

determine_dskb find_maxf_kb

Called from:

entrainment_diffusive

subroutine mom_entrain_diffusive/determine_ea_kb(h_bl, dtKd_kb, Sref, I_dSkbp1, Ent_bl, ea_kbp1, min_eakb, max_eakb, kmb, is, ie, do_i, G, GV, CS, Ent, error, err_min_eakb0, err_max_eakb0, F_kb, dFdfm_kb)

This subroutine determines the entrainment from above by the top interior layer (labeled kb elsewhere) given an entrainment by the layer below it, constrained to be within the provided bounds.

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

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

  • h_bl :: [in] Layer thickness, with the top interior layer at k-index kmb+1 [H ~> m or kg m-2].

  • sref :: [in] The coordinate reference potential density, with the value of the topmost interior layer at layer kmb+1 [R ~> kg m-3].

  • ent_bl :: [in] The average entrainment upward and downward across each interface around the buffer layers [H ~> m or kg m-2].

  • i_dskbp1 :: [in] The inverse of the difference in reference potential density across the base of the uppermost interior layer [R-1 ~> m3 kg-1].

  • dtkd_kb :: [in] The diapycnal diffusivity in the top interior layer times the time step [H2 ~> m2 or kg2 m-4].

  • ea_kbp1 :: [in] The entrainment from above by layer kb+1 [H ~> m or kg m-2].

  • min_eakb :: [in] The minimum permissible rate of entrainment [H ~> m or kg m-2].

  • max_eakb :: [in] The maximum permissible rate of entrainment [H ~> m or kg m-2].

  • kmb :: [in] The number of mixed and buffer layers.

  • is :: [in] The start of the i-index range to work on.

  • ie :: [in] The end of the i-index range to work on.

  • do_i :: [in] A logical variable indicating which i-points to work on.

  • cs :: [in] This module’s control structure.

  • ent :: [inout] The entrainment rate of the uppermost interior layer [H ~> m or kg m-2]. The input value is the first guess.

  • error :: [out] The error (locally defined in this routine) associated with the returned solution [H2 ~> m2 or kg2 m-4]

  • err_min_eakb0 :: [in] The errors (locally defined) associated with min_eakb when ea_kbp1 = 0, returned from a previous call to this subroutine [H2 ~> m2 or kg2 m-4].

  • err_max_eakb0 :: [in] The errors (locally defined) associated with min_eakb when ea_kbp1 = 0, returned from a previous call to this subroutine [H2 ~> m2 or kg2 m-4].

  • f_kb :: [out] The entrainment from below by the uppermost interior layer corresponding to the returned value of Ent [H ~> m or kg m-2].

  • dfdfm_kb :: [out] The partial derivative of F_kb with ea_kbp1 [nondim].

Call to:

determine_dskb mom_error_handler::mom_error

Called from:

entrainment_diffusive

subroutine mom_entrain_diffusive/find_maxf_kb(h_bl, Sref, Ent_bl, I_dSkbp1, min_ent_in, max_ent_in, kmb, is, ie, G, GV, CS, maxF, ent_maxF, do_i_in, F_lim_maxent, F_thresh)

Maximize F = ent*ds_kb*I_dSkbp1 in the range min_ent < ent < max_ent.

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

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

  • h_bl :: [in] Layer thickness [H ~> m or kg m-2]

  • sref :: [in] Reference potential density [R ~> kg m-3].

  • ent_bl :: [in] The average entrainment upward and

  • i_dskbp1 :: [in] The inverse of the difference in reference potential density across the base of the uppermost interior layer [R-1 ~> m3 kg-1].

  • min_ent_in :: [in] The minimum value of ent to search, [H ~> m or kg m-2].

  • max_ent_in :: [in] The maximum value of ent to search, [H ~> m or kg m-2].

  • kmb :: [in] The number of mixed and buffer layers.

  • is :: [in] The start of the i-index range to work on.

  • ie :: [in] The end of the i-index range to work on.

  • cs :: [in] This module’s control structure.

  • maxf :: [out] The maximum value of F = ent*ds_kb*I_dSkbp1 found in the range min_ent < ent < max_ent [H ~> m or kg m-2].

  • ent_maxf :: [out] The value of ent at that maximum [H ~> m or kg m-2].

  • do_i_in :: [in] A logical array indicating which columns

  • f_lim_maxent :: [out] If present, do not apply the limit in

  • f_thresh :: [in] If F_thresh is present, return the first value

Call to:

determine_dskb

Called from:

entrainment_diffusive f_kb_to_ea_kb

subroutine mom_entrain_diffusive/entrain_diffusive_init(Time, G, GV, US, param_file, diag, CS, just_read_params)

This subroutine initializes the parameters and memory associated with the entrain_diffusive module.

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 :: [inout] Entrainment diffusion control structure

  • just_read_params :: [in] If true, this call will only read and log parameters without registering any diagnostics