mom_entrain_diffusive mom_entrain_diffusive::entrain_diffusive_cs subroutine, public subroutine, public mom_entrain_diffusive::entrainment_diffusive (h, tv, fluxes, dt, G, GV, US, CS, ea, eb, kb_out, Kd_Lay, Kd_int) entrainment_diffusive h h tv tv fluxes fluxes dt dt G G GV GV US US CS CS ea ea eb eb kb_out kb_out Kd_Lay Kd_Lay Kd_int 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. g The ocean's grid structure. gv The ocean's vertical grid structure. us A dimensional unit scaling type h Layer thicknesses [H ~> m or kg m-2]. tv A structure containing pointers to any available thermodynamic fields. Absent fields have NULL ptrs. fluxes A structure of surface fluxes that may be used. dt The time increment [T ~> s]. cs The control structure returned by a previous call to entrain_diffusive_init. ea The amount of fluid entrained from the layer eb The amount of fluid entrained from the layer kb_out The index of the lightest layer denser than kd_lay The diapycnal diffusivity of layers kd_int The diapycnal diffusivity of interfaces determine_dskb determine_ea_kb mom_eos::eos_domain f_kb_to_ea_kb f_to_ent find_maxf_kb mom_error_handler::is_root_pe mom_error_handler::mom_error set_ent_bl subroutine subroutine mom_entrain_diffusive::f_to_ent (F, h, kb, kmb, j, G, GV, CS, dsp1_ds, eakb, Ent_bl, ea, eb, do_i_in) f_to_ent F F h h kb kb kmb kmb j j G G GV GV CS CS dsp1_ds dsp1_ds eakb eakb Ent_bl Ent_bl ea ea eb eb do_i_in do_i_in 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. g The ocean's grid structure gv The ocean's vertical grid structure f 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 Layer thicknesses [H ~> m or kg m-2] kb The index of the lightest layer denser than the deepest buffer layer. kmb The number of mixed and buffer layers. j The meridional index upon which to work. cs This module's control structure. dsp1_ds The ratio of coordinate variable differences across the interfaces below a layer over the difference across the interface above the layer. eakb The entrainment from above by the layer below the buffer layer [H ~> m or kg m-2]. ent_bl The average entrainment upward and downward across each interface around the buffer layers [H ~> m or kg m-2]. ea The amount of fluid entrained from the layer eb The amount of fluid entrained from the layer do_i_in Indicates which i-points to work on. entrainment_diffusive subroutine 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) set_ent_bl h h dtKd_int dtKd_int tv tv kb kb kmb kmb do_i do_i G G GV GV US US CS CS j j Ent_bl Ent_bl Sref Sref h_bl 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. g The ocean's grid structure. gv The ocean's vertical grid structure. h Layer thicknesses [H ~> m or kg m-2] dtkd_int The diapycnal diffusivity across tv A structure containing pointers to any available thermodynamic fields. Absent fields have NULL ptrs. kb The index of the lightest layer denser than the buffer layer or 1 if there is no buffer layer. kmb The number of mixed and buffer layers. do_i A logical variable indicating which i-points to work on. us A dimensional unit scaling type cs This module's control structure. j The meridional index upon which to work. ent_bl The average entrainment upward and sref The coordinate potential density minus 1000 for each layer [R ~> kg m-3]. h_bl The thickness of each layer [H ~> m or kg m-2]. mom_eos::eos_domain entrainment_diffusive subroutine 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) determine_dskb h_bl h_bl Sref Sref Ent_bl Ent_bl E_kb E_kb is is ie ie kmb kmb G G GV GV limit limit dSkb dSkb ddSkb_dE ddSkb_dE dSlay dSlay ddSlay_dE ddSlay_dE dS_anom_lim dS_anom_lim do_i_in 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. g The ocean's grid structure. gv The ocean's vertical grid structure. h_bl Layer thickness [H ~> m or kg m-2] sref Reference potential density [R ~> kg m-3] ent_bl The average entrainment upward and downward across each interface around the buffer layers [H ~> m or kg m-2]. e_kb The entrainment by the top interior layer [H ~> m or kg m-2]. is The start of the i-index range to work on. ie The end of the i-index range to work on. kmb The number of mixed and buffer layers. limit If true, limit dSkb and dSlay to avoid negative values. dskb 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 The partial derivative of dSkb with E [R H-1 ~> kg m-4 or m-1]. dslay The limited potential density difference across the topmost interior layer. 0 < dSkb [R ~> kg m-3] ddslay_de The partial derivative of dSlay with E [R H-1 ~> kg m-4 or m-1]. ds_anom_lim A limiting value to use for the density anomalies below the buffer layer [R ~> kg m-3]. do_i_in If present, determines which columns are worked on. mom_error_handler::mom_error determine_ea_kb entrainment_diffusive f_kb_to_ea_kb find_maxf_kb subroutine 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) f_kb_to_ea_kb h_bl h_bl Sref Sref Ent_bl Ent_bl I_dSkbp1 I_dSkbp1 F_kb F_kb kmb kmb i i G G GV GV CS CS ea_kb ea_kb tol_in 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. g The ocean's grid structure gv The ocean's vertical grid structure h_bl Layer thickness, with the top interior sref The coordinate reference potential density, ent_bl The average entrainment upward and downward i_dskbp1 The inverse of the difference in reference potential density across the base of the uppermost interior layer [R-1 ~> m3 kg-1]. f_kb The entrainment from below by the uppermost interior layer [H ~> m or kg m-2] kmb The number of mixed and buffer layers. i The i-index to work on cs This module's control structure. ea_kb The entrainment from above by the layer below the buffer layer (i.e. layer kb) [H ~> m or kg m-2]. tol_in A tolerance for the iterative determination of the entrainment [H ~> m or kg m-2]. determine_dskb find_maxf_kb entrainment_diffusive subroutine 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) determine_ea_kb h_bl h_bl dtKd_kb dtKd_kb Sref Sref I_dSkbp1 I_dSkbp1 Ent_bl Ent_bl ea_kbp1 ea_kbp1 min_eakb min_eakb max_eakb max_eakb kmb kmb is is ie ie do_i do_i G G GV GV CS CS Ent Ent error error err_min_eakb0 err_min_eakb0 err_max_eakb0 err_max_eakb0 F_kb F_kb dFdfm_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. g The ocean's grid structure. gv The ocean's vertical grid structure. h_bl Layer thickness, with the top interior layer at k-index kmb+1 [H ~> m or kg m-2]. sref The coordinate reference potential density, with the value of the topmost interior layer at layer kmb+1 [R ~> kg m-3]. ent_bl The average entrainment upward and downward across each interface around the buffer layers [H ~> m or kg m-2]. i_dskbp1 The inverse of the difference in reference potential density across the base of the uppermost interior layer [R-1 ~> m3 kg-1]. dtkd_kb The diapycnal diffusivity in the top interior layer times the time step [H2 ~> m2 or kg2 m-4]. ea_kbp1 The entrainment from above by layer kb+1 [H ~> m or kg m-2]. min_eakb The minimum permissible rate of entrainment [H ~> m or kg m-2]. max_eakb The maximum permissible rate of entrainment [H ~> m or kg m-2]. kmb The number of mixed and buffer layers. is The start of the i-index range to work on. ie The end of the i-index range to work on. do_i A logical variable indicating which i-points to work on. cs This module's control structure. ent The entrainment rate of the uppermost interior layer [H ~> m or kg m-2]. The input value is the first guess. error The error (locally defined in this routine) associated with the returned solution. err_min_eakb0 The errors (locally defined) associated with min_eakb when ea_kbp1 = 0, returned from a previous call to this fn. err_max_eakb0 The errors (locally defined) associated with min_eakb when ea_kbp1 = 0, returned from a previous call to this fn. f_kb The entrainment from below by the uppermost interior layer corresponding to the returned value of Ent [H ~> m or kg m-2]. dfdfm_kb The partial derivative of F_kb with ea_kbp1 [nondim]. determine_dskb mom_error_handler::mom_error entrainment_diffusive subroutine 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) find_maxf_kb h_bl h_bl Sref Sref Ent_bl Ent_bl I_dSkbp1 I_dSkbp1 min_ent_in min_ent_in max_ent_in max_ent_in kmb kmb is is ie ie G G GV GV CS CS maxF maxF ent_maxF ent_maxF do_i_in do_i_in F_lim_maxent F_lim_maxent F_thresh F_thresh Maximize F = ent*ds_kb*I_dSkbp1 in the range min_ent < ent < max_ent. g The ocean's grid structure. gv The ocean's vertical grid structure. h_bl Layer thickness [H ~> m or kg m-2] sref Reference potential density [R ~> kg m-3]. ent_bl The average entrainment upward and i_dskbp1 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 The minimum value of ent to search, [H ~> m or kg m-2]. max_ent_in The maximum value of ent to search, [H ~> m or kg m-2]. kmb The number of mixed and buffer layers. is The start of the i-index range to work on. ie The end of the i-index range to work on. cs This module's control structure. maxf 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 The value of ent at that maximum [H ~> m or kg m-2]. do_i_in A logical array indicating which columns f_lim_maxent If present, do not apply the limit in f_thresh If F_thresh is present, return the first determine_dskb entrainment_diffusive f_kb_to_ea_kb subroutine, public subroutine, public mom_entrain_diffusive::entrain_diffusive_init (Time, G, GV, US, param_file, diag, CS, just_read_params) entrain_diffusive_init Time Time G G GV GV US US param_file param_file diag diag CS CS just_read_params just_read_params This subroutine initializes the parameters and memory associated with the entrain_diffusive module. time The current model time. g The ocean's grid structure. gv The ocean's vertical grid structure. us A dimensional unit scaling type param_file A structure to parse for run-time parameters. diag A structure that is used to regulate diagnostic output. cs A pointer that is set to point to the control structure. just_read_params If present and true, this call will only read parameters logging them or registering any diagnostics mom_error_handler::mom_error subroutine, public subroutine, public mom_entrain_diffusive::entrain_diffusive_end (CS) entrain_diffusive_end CS CS This subroutine cleans up and deallocates any memory associated with the entrain_diffusive module. cs A pointer to the control structure for this module that will be deallocated. mom_diabatic_driver::diabatic_driver_end Diapycnal mixing and advection in isopycnal mode. 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 neg- ative 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 estim- ated flux in the layer below. This flux is subject to the foll- owing 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.