mom_spatial_means module reference¶

Functions and routines to take area, volume, mass-weighted, layerwise, zonal or meridional means.

Functions/Subroutines¶

`global_area_mean()`	Return the global area mean of a variable, perhaps with a change of units.
`global_area_mean_v()`	Return the global area mean of a variable.
`global_area_mean_u()`	Return the global area mean of a variable on U grid.
`global_area_integral()`	Return the global area integral of a variable using reproducing sums, perhaps with a change of units.
`global_layer_mean()`	Return the layerwise global thickness-weighted mean of a variable.
`global_volume_mean()`	Find the global thickness-weighted mean of a variable.
`global_mass_integral()`	Find the global mass-weighted integral of a variable.
`global_mass_int_efp()`	Find the global mass-weighted order invariant integral of a variable in mks units, returning the value as an EFP_type.
`global_i_mean()`	Determine the global mean of a field along rows of constant i, returning it in a 1-d array using the local indexing.
`global_j_mean()`	Determine the global mean of a field along rows of constant j, returning it in a 1-d array using the local indexing.
`adjust_area_mean_to_zero()`	Adjust 2d array such that area mean is zero without moving the zero contour.
`array_global_min_max()`	Find the global maximum and minimum of a tracer array and return the locations of the extrema.
`ijk_loc()`

Detailed Description¶

Functions and routines to take area, volume, mass-weighted, layerwise, zonal or meridional means.

Function/Subroutine Documentation¶

function mom_spatial_means/global_area_mean(var, G, scale, tmp_scale, unscale) [real]¶

Return the global area mean of a variable, perhaps with a change of units. This uses reproducing sums.

Parameters:

g :: [in] The ocean’s grid structure
var :: [in] The variable to average in arbitrary units [a], or arbitrary rescaled units [A ~> a] if unscale or tmp_scale is present arbitrary, possibly rescaled units [A ~> a]
scale :: [in] A rescaling factor for the variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums
tmp_scale :: [in] A temporary rescaling factor for the variable that is reversed in the return value [a A-1 ~> 1], or [b B-1 ~> 1] if unscale is also present.
unscale :: [in] A rescaling factor for the variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums, or a factor converting between rescaled units if tmp_scale is also present [B A-1 ~> b a-1]. Here scale and unscale are synonymous, but unscale is preferred and takes precedence.

function mom_spatial_means/global_area_mean_v(var, G, tmp_scale) [real]¶

Return the global area mean of a variable. This uses reproducing sums.

Parameters:

g :: [in] The ocean’s grid structure
var :: [in] The variable to average in arbitrary units [a], or arbitrary rescaled units [A ~> a] if tmp_scale is present
tmp_scale :: [in] A temporary rescaling factor for the variable that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums [a A-1 ~> 1], but is reversed before output so that the return value has the same units as var

Called from:

mom_forcing_type::homogenize_field_v mom_forcing_type::homogenize_mech_forcing

function mom_spatial_means/global_area_mean_u(var, G, tmp_scale) [real]¶

Return the global area mean of a variable on U grid. This uses reproducing sums.

Parameters:

g :: [in] The ocean’s grid structure
var :: [in] The variable to average in arbitrary units [a], or arbitrary rescaled units [A ~> a] if tmp_scale is present
tmp_scale :: [in] A temporary rescaling factor for the variable that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums [a A-1 ~> 1], but is reversed before output so that the return value has the same units as var

Called from:

mom_forcing_type::homogenize_field_u mom_forcing_type::homogenize_mech_forcing

function mom_spatial_means/global_area_integral(var, G, scale, area, tmp_scale, unscale) [real]¶

Return the global area integral of a variable using reproducing sums, perhaps with a change of units. By default the integral uses the masked area from the grid, but an alternate could be used instead. The presence of the optional tmp_scale argument determines whether the returned value is in scaled (if it is present) or unscaled units for both the variable itself and for the area in the integral.

Parameters:

g :: [in] The ocean’s grid structure
var :: [in] The variable to integrate in arbitrary units [a], or arbitrary rescaled units [A ~> a] if unscale or tmp_scale is present
scale :: [in] A rescaling factor for the variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums
area :: [in] The alternate area to use, including any required masking [L2 ~> m2].
tmp_scale :: [in] A temporary rescaling factor for the variable that is reversed in the return value [a A-1 ~> 1], or [b B-1 ~> 1] if unscale is also present.
unscale :: [in] A rescaling factor for the variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums, or a factor converting between rescaled units if tmp_scale is also present [B A-1 ~> b a-1]. Here scale and unscale are synonymous, but unscale is preferred and takes precedence if both are present.

Return:

undefined :: The returned area integral, usually in the units of var times an area, [a m2] or [A L2 ~> a m2] or [B L2 ~> b m2], depending on which optional arguments are provided

Called from:

mom_ice_shelf::add_shelf_flux mom_diagnose_kdwork::kdwork_diagnostics mom_diagnostics::post_surface_thermo_diags mom_internal_tides::propagate_int_tide mom_internal_tides::sum_en

function mom_spatial_means/global_layer_mean(var, h, G, GV, scale, tmp_scale, unscale) [real]¶

Return the layerwise global thickness-weighted mean of a variable. This uses reproducing sums.

Parameters:

g :: [in] The ocean’s grid structure
gv :: [in] The ocean’s vertical grid structure
var :: [in] The variable to average in arbitrary units [a], or arbitrary rescaled units [A ~> a] if unscale or tmp_scale is present
h :: [in] Layer thicknesses [H ~> m or kg m-2]
scale :: [in] A rescaling factor for the variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums
tmp_scale :: [in] A temporary rescaling factor for the variable for use in the reproducing sums that is reversed in the return value [a A-1 ~> 1], or [b B-1 ~> 1] if unscale is also present.
unscale :: [in] A rescaling factor for the variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums, or a factor converting between rescaled units if tmp_scale is also present [B A-1 ~> b a-1]. Here scale and unscale are synonymous, but unscale is preferred and takes precedence.

Return:

undefined :: The mean of the variable in the arbitrary scaled [A ~> a] or [B ~> b] or unscaled [a] units of var, depending on which optional arguments are provided

function mom_spatial_means/global_volume_mean(var, h, G, GV, scale, tmp_scale, unscale) [real]¶

Find the global thickness-weighted mean of a variable. This uses reproducing sums.

Parameters:

g :: [in] The ocean’s grid structure
gv :: [in] The ocean’s vertical grid structure
var :: [in] The variable to average in arbitrary units [a],
h :: [in] Layer thicknesses [H ~> m or kg m-2]
scale :: [in] A rescaling factor for the variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums
tmp_scale :: [in] A temporary rescaling factor for the variable that is reversed in the return value [a A-1 ~> 1], or [b B-1 ~> 1] if unscale is also present.
unscale :: [in] A rescaling factor for the variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums, or a factor converting between rescaled units if tmp_scale is also present [B A-1 ~> b a-1]. Here scale and unscale are synonymous, but unscale is preferred and takes precedence if both are present.

Return:

undefined :: The thickness-weighted average of var in the arbitrary scaled [A ~> a] or [B ~> b] or unscaled [a] units of var, depending on which optional arguments are provided

Called from:

mom_diagnostics::calculate_diagnostic_fields

function mom_spatial_means/global_mass_integral(h, G, GV, var, on_PE_only, scale, tmp_scale, unscale) [real]¶

Find the global mass-weighted integral of a variable. The presence of the optional tmp_scale argument determines whether the returned value is in scaled (if it is present) or unscaled units for both the variable itself and for the mass in the integral. This function uses reproducing sums.

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]
var :: [in] The variable to integrate in arbitrary units [a],
on_pe_only :: [in] If present and true, the sum is only done on the local PE, and it is not order invariant.
scale :: [in] A rescaling factor for the variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums
tmp_scale :: [in] A temporary rescaling factor for the variable that is reversed in the return value [a A-1 ~> 1], or [b B-1 ~> 1] if unscale is also present.
unscale :: [in] A rescaling factor for the variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums, or a factor converting between rescaled units if tmp_scale is also present [B A-1 ~> b a-1]. Here scale and unscale are synonymous, but unscale is preferred and takes precedence if both are present.

Return:

undefined :: The mass-weighted integral of var (or 1) in kg times the arbitrary units of var [kg a] or in [R Z L2 A ~> kg a] if tmp_scale is present or [R Z L2 B ~> kg b] if both unscale and tmp_scale are present

Called from:

mom::get_ocean_stocks mom_hor_bnd_diffusion::hor_bnd_diffusion

function mom_spatial_means/global_mass_int_efp(h, G, GV, var, on_PE_only, scale, unscale) [type(efp_type)]¶

Find the global mass-weighted order invariant integral of a variable in mks units, returning the value as an EFP_type. This uses reproducing sums.

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]
var :: [in] The variable to integrate in arbitrary units [a],
on_pe_only :: [in] If present and true, the sum is only done on the local PE, but it is still order invariant.
scale :: [in] A rescaling factor for the variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums
unscale :: [in] A rescaling factor for the variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums. Here scale and unscale are synonymous, but unscale is preferred and takes precedence if both are present.

Return:

undefined :: The mass-weighted integral of var (or 1) in kg times the arbitrary units of var [kg a]

Called from:

advection_test_tracer::advection_test_stock boundary_impulse_tracer::boundary_impulse_stock mom_cfc_cap::cfc_cap_stock regional_dyes::dye_stock ideal_age_example::ideal_age_stock marbl_tracers::marbl_tracers_stock mom_ocmip2_cfc::ocmip2_cfc_stock oil_tracer::oil_stock pseudo_salt_tracer::pseudo_salt_stock user_tracer_example::user_tracer_stock

subroutine mom_spatial_means/global_i_mean(array, i_mean, G, mask, scale, tmp_scale, unscale)¶

Determine the global mean of a field along rows of constant i, returning it in a 1-d array using the local indexing. This uses reproducing sums.

Parameters:

g :: [inout] The ocean’s grid structure
array :: [in] The variable to integrate in arbitrary units [a], or arbitrary rescaled units [A ~> a] if unscale is present
i_mean :: [out] Global mean of array along its i-axis [a] or [A ~> a]
mask :: [in] An array used for weighting the i-mean [nondim]
scale :: [in] A rescaling factor for the output variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums
tmp_scale :: [in] A rescaling factor for the internal calculations that is removed from the output [a A-1 ~> 1]
unscale :: [in] A rescaling factor for the variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums. Here scale and unscale are synonymous, but unscale is preferred and takes precedence if both are present.

Call to:

mom_error_handler::mom_error

Called from:

mom_sponge::apply_sponge

subroutine mom_spatial_means/global_j_mean(array, j_mean, G, mask, scale, tmp_scale, unscale)¶

Determine the global mean of a field along rows of constant j, returning it in a 1-d array using the local indexing. This uses reproducing sums.

Parameters:

g :: [inout] The ocean’s grid structure
array :: [in] The variable to integrate in arbitrary units [a], or arbitrary rescaled units [A ~> a] if unscale is present
j_mean :: [out] Global mean of array along its j-axis [a] or [A ~> a]
mask :: [in] An array used for weighting the j-mean [nondim]
scale :: [in] A rescaling factor for the output variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums
tmp_scale :: [in] A rescaling factor for the internal calculations that is removed from the output [a A-1 ~> 1]
unscale :: [in] A rescaling factor for the variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums. Here scale and unscale are synonymous, but unscale is preferred and takes precedence if both are present.

Call to:

mom_error_handler::mom_error

subroutine mom_spatial_means/adjust_area_mean_to_zero(array, G, scaling, unit_scale, unscale)¶

Adjust 2d array such that area mean is zero without moving the zero contour.

Parameters:

g :: [in] Grid structure
array :: [inout] 2D array to be adjusted in arbitrary units [a], or arbitrary rescaled units [A ~> a] if unscale is present
scaling :: [out] The scaling factor used [nondim]
unit_scale :: [in] A rescaling factor for the variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums
unscale :: [in] A rescaling factor for the variable [a A-1 ~> 1] that converts it back to unscaled (e.g., mks) units to enable the use of the reproducing sums. Here unit_scale and unscale are synonymous, but unscale is preferred and takes precedence if both are present.

Called from:

mom_surface_forcing_gfdl::convert_iob_to_fluxes

subroutine mom_spatial_means/array_global_min_max(tr_array, G, nk, g_min, g_max, xgmin, ygmin, zgmin, xgmax, ygmax, zgmax, unscale)¶

Find the global maximum and minimum of a tracer array and return the locations of the extrema. When there multiple cells with the same extreme values, the reported locations are from the uppermost layer where they occur, and then from the logically northernmost and then eastermost such location on the unrotated version of the grid within that layer. Only ocean points (as indicated by a positive value of Gmask2dT) are evaluated, and if there are no ocean points anywhere in the domain, the reported extrema and their locations are all returned as 0.

Parameters:

nk :: [in] The number of vertical levels
g :: [in] The ocean’s grid structure
tr_array :: [in] The tracer array to search for extrema in arbitrary concentration units [CU ~> conc]
g_min :: [out] The global minimum of tr_array, either in the same units as tr_array [CU ~> conc] or in unscaled units if unscale is present [conc]
g_max :: [out] The global maximum of tr_array, either in the same units as tr_array [CU ~> conc] or in unscaled units if unscale is present [conc]
xgmin :: [out] The x-position of the global minimum in the units of GgeoLonT, often [degrees_E] or [km] or [m]
ygmin :: [out] The y-position of the global minimum in the units of GgeoLatT, often [degrees_N] or [km] or [m]
zgmin :: [out] The z-position of the global minimum [layer]
xgmax :: [out] The x-position of the global maximum in the units of GgeoLonT, often [degrees_E] or [km] or [m]
ygmax :: [out] The y-position of the global maximum in the units of GgeoLatT, often [degrees_N] or [km] or [m]
zgmax :: [out] The z-position of the global maximum [layer]
unscale :: [in] A factor to use to undo any scaling of the input tracer array [conc CU-1 ~> 1]

Call to:

ijk_loc

Called from:

mom_sum_output::write_energy

function mom_spatial_means/ijk_loc(i, j, k, nk, HI) [integer]¶

Parameters:

i :: [in] Local i-index
j :: [in] Local j-index
k :: [in] Local k-index
nk :: [in] Range of k-index, used to pick out a low-k position.
hi :: [in] Horizontal index ranges

Called from:

array_global_min_max