mom_opacity module reference¶

Routines used to calculate the opacity of the ocean.

Data Types¶

`optics_type`	This type is used to store information about ocean optical properties.
`opacity_cs`	The control structure with parameters for the MOM_opacity module.

Functions/Subroutines¶

`set_opacity()`	This sets the opacity of sea water based based on one of several different schemes.
`opacity_from_chl()`	This sets the “blue” band opacity based on chlorophyll A concentrations The red portion is lumped into the net heating at the surface.
`opacity_morel()`	This sets the blue-wavelength opacity according to the scheme proposed by Morel and Antoine (1994).
`sw_pen_frac_morel()`	This sets the penetrating shortwave fraction according to the scheme proposed by Morel and Antoine (1994).
`opacity_manizza()`	This sets the blue-wavelength opacity according to the scheme proposed by Manizza, M.
`extract_optics_slice()`	This subroutine returns a 2-d slice at constant j of fields from an `optics_type()`, with the potential for rescaling these fields.
`extract_optics_fields()`	Set arguments to fields from the optics type.
`optics_nbands()`	Return the number of bands of penetrating shortwave radiation.
`absorbremainingsw()`	Apply shortwave heating below the boundary layer (when running with the bulk mixed layer inherited from GOLD) or throughout the water column.
`sumswoverbands()`	This subroutine calculates the total shortwave heat flux integrated over bands as a function of depth.
`opacity_init()`	This routine initializes the opacity module, including an `optics_type()`.
`opacity_end()`

Detailed Description¶

opacity_from_chl: In this routine, the Morel (modified) or Manizza (modified) schemes use the “blue” band in the parameterizations to determine the e-folding depth of the incoming shortwave attenuation. The red portion is lumped into the net heating at the surface.

Morel, A., 1988: Optical modeling of the upper ocean in relation to its biogenous matter content (case-i waters)., J. Geo. Res., 93, 10,749-10,768.

Manizza, M., C. LeQuere, A. J. Watson, and E. T. Buitenhuis, 2005: Bio-optical feedbacks among phytoplankton, upper ocean physics and sea-ice in a global model, Geophys. Res. Let., 32, L05603, doi:10.1029/2004GL020778.

Type Documentation¶

type mom_opacity/optics_type¶

This type is used to store information about ocean optical properties.

Type fields:

% nbands [integer] :: The number of penetrating bands of SW radiation.
% opacity_band [real(:,:,:,:),allocatable] :: SW optical depth per unit thickness [Z-1 ~> m-1] The number of radiation bands is most rapidly varying (first) index.
% sw_pen_band [real(:,:,:),allocatable] :: shortwave radiation [Q R Z T-1 ~> W m-2] at the surface in each of the nbands bands that penetrates beyond the surface. The most rapidly varying dimension is the band.
% min_wavelength_band [real(:),allocatable] :: The minimum wavelength in each band of penetrating shortwave radiation [nm].
% max_wavelength_band [real(:),allocatable] :: The maximum wavelength in each band of penetrating shortwave radiation [nm].
% pensw_flux_absorb [real] :: A heat flux that is small enough to be completely absorbed in the next sufficiently thick layer [C H T-1 ~> degC m s-1 or degC kg m-2 s-1].
% pensw_absorb_invlen [real] :: The inverse of the thickness that is used to absorb the remaining shortwave heat flux when it drops below PEN_SW_FLUX_ABSORB [H ~> m or kg m-2].
% answer_date [integer] :: The vintage of the order of arithmetic and expressions in the optics calculations. Values below 20190101 recover the answers from the end of 2018, while higher values use updated and more robust forms of the same expressions.

type mom_opacity/opacity_cs¶

The control structure with parameters for the MOM_opacity module.

Type fields:

% id_sw_pen [integer] :: Diagnostic IDs.
% id_sw_vis_pen [integer] :: Diagnostic IDs.
% id_opacity [integer(:),allocatable] :: Diagnostic IDs.
% var_pen_sw [logical] :: If true, use one of the CHL_A schemes (specified by OPACITY_SCHEME) to determine the e-folding depth of incoming shortwave radiation.
% opacity_scheme [integer] :: An integer indicating which scheme should be used to translate water properties into the opacity (i.e., the e-folding depth) and (perhaps) the number of bands of penetrating shortwave radiation to use.
% pen_sw_scale [real] :: The vertical absorption e-folding depth of the penetrating shortwave radiation [Z ~> m].
% pen_sw_scale_2nd [real] :: The vertical absorption e-folding depth of the (2nd) penetrating shortwave radiation [Z ~> m].
% sw_1st_exp_ratio [real] :: Ratio for 1st exp decay in Two Exp decay opacity [nondim].
% pen_sw_frac [real] :: The fraction of shortwave radiation that is penetrating with a constant e-folding approach [nondim].
% blue_frac [real] :: The fraction of the penetrating shortwave radiation that is in the blue band [nondim].
% opacity_land_value [real] :: The value to use for opacity over land [Z-1 ~> m-1]. The default is 10 m-1 - a value for muddy water.
% diag [type( diag_ctrl ),pointer] :: A structure that is used to regulate the timing of diagnostic output.
% warning_issued [logical] :: A flag that is used to avoid repetitive warnings.

Function/Subroutine Documentation¶

subroutine mom_opacity/set_opacity(optics, sw_total, sw_vis_dir, sw_vis_dif, sw_nir_dir, sw_nir_dif, G, GV, US, CS, chl_2d, chl_3d)¶

This sets the opacity of sea water based based on one of several different schemes.

Parameters:

optics :: [inout] An optics structure that has values set based on the opacities.
sw_total :: Total shortwave flux into the ocean [Q R Z T-1 ~> W m-2]
sw_vis_dir :: Visible, direct shortwave into the ocean [Q R Z T-1 ~> W m-2]
sw_vis_dif :: Visible, diffuse shortwave into the ocean [Q R Z T-1 ~> W m-2]
sw_nir_dir :: Near-IR, direct shortwave into the ocean [Q R Z T-1 ~> W m-2]
sw_nir_dif :: Near-IR, diffuse shortwave into the ocean [Q R Z T-1 ~> W m-2]
g :: [in] The ocean’s grid structure.
gv :: [in] The ocean’s vertical grid structure.
us :: [in] A dimensional unit scaling type
cs :: The control structure earlier set up by opacity_init.
chl_2d :: [in] Vertically uniform chlorophyll-A concentrations [mg m-3]
chl_3d :: [in] The chlorophyll-A concentrations of each layer [mg m-3]

Call to:

double_exp manizza_05 opacity_from_chl mom_diag_mediator::query_averaging_enabled

subroutine mom_opacity/opacity_from_chl(optics, sw_total, sw_vis_dir, sw_vis_dif, sw_nir_dir, sw_nir_dif, G, GV, US, CS, chl_2d, chl_3d)¶

This sets the “blue” band opacity based on chlorophyll A concentrations The red portion is lumped into the net heating at the surface.

Parameters:

optics :: [inout] An optics structure that has values set based on the opacities.
sw_total :: Total shortwave flux into the ocean [Q R Z T-1 ~> W m-2]
sw_vis_dir :: Visible, direct shortwave into the ocean [Q R Z T-1 ~> W m-2]
sw_vis_dif :: Visible, diffuse shortwave into the ocean [Q R Z T-1 ~> W m-2]
sw_nir_dir :: Near-IR, direct shortwave into the ocean [Q R Z T-1 ~> W m-2]
sw_nir_dif :: Near-IR, diffuse shortwave into the ocean [Q R Z T-1 ~> W m-2]
g :: [in] The ocean’s grid structure.
gv :: [in] The ocean’s vertical grid structure.
us :: [in] A dimensional unit scaling type
cs :: The control structure.
chl_2d :: [in] Vertically uniform chlorophyll-A concentrations [mg m-3]
chl_3d :: [in] A 3-d field of chlorophyll-A concentrations [mg m-3]

Call to:

manizza_05 mom_error_handler::mom_error morel_88 opacity_morel sw_pen_frac_morel

Called from:

set_opacity

function mom_opacity/opacity_morel(chl_data) [real]¶

This sets the blue-wavelength opacity according to the scheme proposed by Morel and Antoine (1994).

Parameters:: chl_data :: [in] The chlorophyll-A concentration in [mg m-3]
Return:: undefined :: The returned opacity [m-1]
Called from:: opacity_from_chl

function mom_opacity/sw_pen_frac_morel(chl_data) [real]¶

This sets the penetrating shortwave fraction according to the scheme proposed by Morel and Antoine (1994).

Parameters:: chl_data :: [in] The chlorophyll-A concentration [mg m-3]
Return:: undefined :: The returned penetrating shortwave fraction [nondim]
Called from:: opacity_from_chl

function mom_opacity/opacity_manizza(chl_data) [real]¶

This sets the blue-wavelength opacity according to the scheme proposed by Manizza, M. et al, 2005.

Parameters:: chl_data :: [in] The chlorophyll-A concentration [mg m-3]
Return:: undefined :: The returned opacity [m-1]

subroutine mom_opacity/extract_optics_slice(optics, j, G, GV, opacity, opacity_scale, penSW_top, penSW_scale, SpV_avg)¶

This subroutine returns a 2-d slice at constant j of fields from an optics_type(), with the potential for rescaling these fields. , with the potential for rescaling these fields.

Parameters:

optics :: [in] An optics structure that has values of opacities and shortwave fluxes.
j :: [in] j-index to extract
g :: [in] The ocean’s grid structure.
gv :: [in] The ocean’s vertical grid structure.
opacity :: [out] The opacity in each band, i-point, and layer [Z-1 ~> m-1],
opacity_scale :: [in] A factor by which to rescale the opacity [nondim] or [Z H-1 ~> 1 or m3 kg-1]
pensw_top :: [out] The shortwave radiation [Q R Z T-1 ~> W m-2]
pensw_scale :: [in] A factor by which to rescale the shortwave flux [nondim] or other units.
spv_avg :: [in] The layer-averaged specific volume [R-1 ~> m3 kg-1]

Called from:

mom_bulk_mixed_layer::bulkmixedlayer mom_forcing_type::extractfluxes1d

subroutine mom_opacity/extract_optics_fields(optics, nbands)¶

Set arguments to fields from the optics type.

Parameters:

optics :: [in] An optics structure that has values of opacities and shortwave fluxes.
nbands :: [out] The number of penetrating bands of SW radiation

function mom_opacity/optics_nbands(optics) [integer]¶

Return the number of bands of penetrating shortwave radiation.

Parameters:: optics :: An optics structure that has values of opacities and shortwave fluxes.
Return:: undefined :: The number of penetrating bands of SW radiation
Called from:: mom_forcing_type::calculatebuoyancyflux1d mom_forcing_type::calculatebuoyancyflux2d mom_diabatic_driver::diabatic_ale mom_diabatic_driver::diabatic_ale_legacy mom_forcing_type::extractfluxes1d

subroutine mom_opacity/absorbremainingsw(G, GV, US, h, opacity_band, nsw, optics, j, dt, H_limit_fluxes, adjustAbsorptionProfile, absorbAllSW, T, Pen_SW_bnd, eps, ksort, htot, Ttot, TKE, dSV_dT)¶

Apply shortwave heating below the boundary layer (when running with the bulk mixed layer inherited from GOLD) or throughout the water column.

In addition, it causes all of the remaining SW radiation to be absorbed, provided that the total water column thickness is greater than H_limit_fluxes. For thinner water columns, the heating is scaled down proportionately, the assumption being that the remaining heating (which is left in Pen_SW) should go into an (absent for now) ocean bottom sediment layer.

Parameters:

g :: [in] The ocean’s grid structure.
gv :: [in] The ocean’s vertical grid structure.
us :: [in] A dimensional unit scaling type
nsw :: [in] Number of bands of penetrating shortwave radiation.
h :: [in] Layer thicknesses [H ~> m or kg m-2].
opacity_band :: [in] Opacity in each band of penetrating shortwave radiation [H-1 ~> m-1 or m2 kg-1]. The indices are band, i, k.
optics :: [in] An optics structure that has values of opacities and shortwave fluxes.
j :: [in] j-index to work on.
dt :: [in] Time step [T ~> s].
h_limit_fluxes :: [in] If the total ocean depth is less than this, they are scaled away to avoid numerical instabilities [H ~> m or kg m-2]. This would not be necessary if a finite heat capacity mud-layer were added.
adjustabsorptionprofile :: [in] If true, apply heating above the layers in which it should have occurred to get the correct mean depth (and potential energy change) of the shortwave that should be absorbed by each layer.
absorballsw :: [in] If true, apply heating above the layers in which it should have occurred to get the correct mean depth (and potential energy change) of the shortwave that should be absorbed by each layer.
t :: [inout] Layer potential/conservative temperatures [C ~> degC]
pen_sw_bnd :: [inout] Penetrating shortwave heating in each band that hits the bottom and will will be redistributed through the water column [C H ~> degC m or degC kg m-2], size nsw x G isd: G ied.
eps :: [in] Small thickness that must remain in each layer, and which will not be subject to heating [H ~> m or kg m-2]
ksort :: [in] Density-sorted k-indices.
htot :: [in] Total mixed layer thickness [H ~> m or kg m-2].
ttot :: [inout] Depth integrated mixed layer temperature [C H ~> degC m or degC kg m-2]
dsv_dt :: [in] The partial derivative of specific volume with temperature [R-1 C-1 ~> m3 kg-1 degC-1]
tke :: [inout] The TKE sink from mixing the heating throughout a layer [R Z3 T-2 ~> J m-2].

Called from:

mom_diabatic_aux::applyboundaryfluxesinout mom_bulk_mixed_layer::bulkmixedlayer

subroutine mom_opacity/sumswoverbands(G, GV, US, h, dz, nsw, optics, j, dt, H_limit_fluxes, absorbAllSW, iPen_SW_bnd, netPen)¶

This subroutine calculates the total shortwave heat flux integrated over bands as a function of depth. This routine is only called for computing buoyancy fluxes for use in KPP. This routine does not update the state.

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].
dz :: [in] Layer vertical extent [Z ~> m].
nsw :: [in] The number of bands of penetrating shortwave radiation, perhaps from optics_nbands(optics),
optics :: [in] An optics structure that has values set based on the opacities.
j :: [in] j-index to work on.
dt :: [in] Time step [T ~> s].
h_limit_fluxes :: [in] the total depth at which the surface fluxes start to be limited to avoid excessive heating of a thin ocean [H ~> m or kg m-2]
absorballsw :: [in] If true, ensure that all shortwave radiation is absorbed in the ocean water column.
ipen_sw_bnd :: [in] The incident penetrating shortwave in each band at the sea surface; size nsw x G isd: G ied [C H ~> degC m or degC kg m-2].
netpen :: [inout] Net penetrating shortwave heat flux at each

Called from:

mom_forcing_type::calculatebuoyancyflux1d

subroutine mom_opacity/opacity_init(Time, G, GV, US, param_file, diag, CS, optics)¶

This routine initializes the opacity module, including an optics_type(). .

Parameters:

time :: [in] The current model time.
g :: [in] The ocean’s grid structure.
gv :: [in] model 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 :: Opacity control structure
optics :: An optics structure that has parameters set and arrays allocated here.

Call to:

double_exp double_exp_string manizza_05 manizza_05_string mom_error_handler::mom_error mom_error_handler::mom_mesg morel_88 morel_88_string no_scheme mom_diag_mediator::register_diag_field single_exp single_exp_string mom_string_functions::uppercase

subroutine mom_opacity/opacity_end(CS, optics)¶

Parameters:

cs :: Opacity control structure
optics :: An optics type structure that should be deallocated.