7.1.6. mom_tracer_flow_control module reference¶

Orchestrates the registration and calling of tracer packages.

7.1.6.1. Data Types¶

tracer_flow_control_cs

The control structure for orchestrating the calling of tracer packages.

7.1.6.2. Functions/Subroutines¶

`call_tracer_flux_init()`	This subroutine carries out a series of calls to initialize the air-sea tracer fluxes, but it does not record the generated indicies, and it may be called before the ocean model has been initialized and may be called on non-ocean PEs.
`call_tracer_register()`	This subroutine determines which tracer packages are to be used and does the calls to register their tracers to be advected, diffused, and read from restarts.
`tracer_flow_control_init()`	This subroutine calls all registered tracer initialization subroutines.
`call_tracer_register_obc_segments()`	This subroutine calls all registered tracers to register their OBC segments similar to register_temp_salt_segments for T&S.
`get_chl_from_model()`	This subroutine extracts the chlorophyll concentrations from the model state, if possible.
`call_tracer_set_forcing()`	This subroutine calls the individual tracer modules’ subroutines to specify or read quantities related to their surface forcing.
`call_tracer_column_fns()`	This subroutine calls all registered tracer column physics subroutines.
`call_tracer_stocks()`	This subroutine calls all registered tracer packages to enable them to add to the surface state returned to the coupler.
`store_stocks()`	This routine stores the stocks and does error handling for call_tracer_stocks.
`call_tracer_surface_state()`	This subroutine calls all registered tracer packages to enable them to add to the surface state returned to the coupler.
`tracer_flow_control_end()`

7.1.6.3. Detailed Description¶

Orchestrates the registration and calling of tracer packages.

7.1.6.4. Type Documentation¶

type mom_tracer_flow_control/tracer_flow_control_cs¶

The control structure for orchestrating the calling of tracer packages.

Type fields

% user_tracer_example_csp [type(user_tracer_example_cs),pointer] :: Pointers to the control strucures for the tracer packages.
% dome_tracer_csp [type(dome_tracer_cs),pointer] :: Pointers to the control strucures for the tracer packages.
% isomip_tracer_csp [type(isomip_tracer_cs),pointer] :: Pointers to the control strucures for the tracer packages.
% rgc_tracer_csp [type(rgc_tracer_cs),pointer] :: Pointers to the control strucures for the tracer packages.
% ideal_age_tracer_csp [type(ideal_age_tracer_cs),pointer] :: Pointers to the control strucures for the tracer packages.
% marbl_tracers_csp [type(marbl_tracers_cs),pointer] :: Pointers to the control strucures for the tracer packages.
% dye_tracer_csp [type(dye_tracer_cs),pointer] :: Pointers to the control strucures for the tracer packages.
% oil_tracer_csp [type(oil_tracer_cs),pointer] :: Pointers to the control strucures for the tracer packages.
% advection_test_tracer_csp [type(advection_test_tracer_cs),pointer] :: Pointers to the control strucures for the tracer packages.
% ocmip2_cfc_csp [type(ocmip2_cfc_cs),pointer] :: Pointers to the control strucures for the tracer packages.
% cfc_cap_csp [type(cfc_cap_cs),pointer] :: Pointers to the control strucures for the tracer packages.
% mom_generic_tracer_csp [type(mom_generic_tracer_cs),pointer] :: Pointers to the control strucures for the tracer packages.
% pseudo_salt_tracer_csp [type(pseudo_salt_tracer_cs),pointer] :: Pointers to the control strucures for the tracer packages.
% boundary_impulse_tracer_csp [type(boundary_impulse_tracer_cs),pointer] :: Pointers to the control strucures for the tracer packages.
% dyed_obc_tracer_csp [type(dyed_obc_tracer_cs),pointer] :: Pointers to the control strucures for the tracer packages.
% nw2_tracers_csp [type(nw2_tracers_cs),pointer] :: Pointers to the control strucures for the tracer packages.
% use_user_tracer_example [logical] :: If true, use the USER_tracer_example package.
% use_dome_tracer [logical] :: If true, use the DOME_tracer package.
% use_isomip_tracer [logical] :: If true, use the ISOMPE_tracer package.
% use_rgc_tracer [logical] :: If true, use the RGC_tracer package.
% use_ideal_age [logical] :: If true, use the ideal age tracer package.
% use_marbl_tracers [logical] :: If true, use the MARBL tracer package.
% use_regional_dyes [logical] :: If true, use the regional dyes tracer package.
% use_oil [logical] :: If true, use the oil tracer package.
% use_advection_test_tracer [logical] :: If true, use the advection_test_tracer package.
% use_ocmip2_cfc [logical] :: If true, use the OCMIP2_CFC tracer package.
% use_cfc_cap [logical] :: If true, use the CFC_cap tracer package.
% use_mom_generic_tracer [logical] :: If true, use the MOM_generic_tracer packages.
% use_pseudo_salt_tracer [logical] :: If true, use the psuedo_salt tracer package.
% use_boundary_impulse_tracer [logical] :: If true, use the boundary impulse tracer package.
% use_dyed_obc_tracer [logical] :: If true, use the dyed OBC tracer package.
% use_nw2_tracers [logical] :: If true, use the NW2 tracer package.
% get_chl_from_marbl [logical] :: If true, use the MARBL-provided Chl for shortwave penetration.

7.1.6.5. Function/Subroutine Documentation¶

subroutine mom_tracer_flow_control/call_tracer_flux_init(verbosity)¶

This subroutine carries out a series of calls to initialize the air-sea tracer fluxes, but it does not record the generated indicies, and it may be called before the ocean model has been initialized and may be called on non-ocean PEs. It is not necessary to call this routine for ocean-only runs, because the same calls are made again inside of the routines called by call_tracer_register.

Parameters: verbosity :: [in] A 0-9 integer indicating a level of verbosity.

subroutine mom_tracer_flow_control/call_tracer_register(G, GV, US, param_file, CS, tr_Reg, restart_CS)¶

This subroutine determines which tracer packages are to be used and does the calls to register their tracers to be advected, diffused, and read from restarts.

Parameters

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.
cs :: A pointer that is set to point to the control structure for this module.
tr_reg :: A pointer that is set to point to the control structure for the tracer advection and diffusion module.
restart_cs :: [inout] A pointer to the restart control structure.

subroutine mom_tracer_flow_control/tracer_flow_control_init(restart, day, G, GV, US, h, param_file, diag, OBC, CS, sponge_CSp, ALE_sponge_CSp, tv)¶

This subroutine calls all registered tracer initialization subroutines.

Parameters

restart :: [in] 1 if the fields have already been read from a restart file.
day :: [in] Time of the start of the run.
g :: [inout] 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]
param_file :: [in] A structure to parse for run-time parameters
diag :: [in] A structure that is used to regulate diagnostic output.
obc :: This open boundary condition type specifies whether, where, and what open boundary conditions are used.
cs :: The control structure returned by a previous call to call_tracer_register.
sponge_csp :: A pointer to the control structure for the sponges, if they are in use. Otherwise this may be unassociated.
ale_sponge_csp :: A pointer to the control structure for the ALE sponges, if they are in use. Otherwise this may be unassociated.
tv :: [in] A structure pointing to various thermodynamic variables

subroutine mom_tracer_flow_control/call_tracer_register_obc_segments(GV, param_file, CS, tr_Reg, OBC)¶

This subroutine calls all registered tracers to register their OBC segments similar to register_temp_salt_segments for T&S.

Parameters

gv :: [in] The ocean’s vertical grid structure.
param_file :: [in] A structure to parse for run-time parameters.
cs :: A pointer that is set to point to the control structure for this module.
tr_reg :: A pointer that is set to point to the control structure for the tracer advection and diffusion module.
obc :: This open boundary condition type specifies whether, where, and what open boundary conditions are used.

subroutine mom_tracer_flow_control/get_chl_from_model(Chl_array, G, GV, CS)¶

This subroutine extracts the chlorophyll concentrations from the model state, if possible.

Parameters

g :: [in] The ocean’s grid structure.
gv :: [in] The ocean’s vertical grid structure.
chl_array :: [out] The array in which to store the model’s
cs :: The control structure returned by a previous call to call_tracer_register.

subroutine mom_tracer_flow_control/call_tracer_set_forcing(sfc_state, fluxes, day_start, day_interval, G, US, Rho0, CS)¶

This subroutine calls the individual tracer modules’ subroutines to specify or read quantities related to their surface forcing.

Parameters

sfc_state :: [inout] A structure containing fields that describe the surface state of the ocean.
fluxes :: [inout] A structure containing pointers to any possible forcing fields. Unused fields have NULL ptrs.
day_start :: [in] Start time of the fluxes.
day_interval :: [in] Length of time over which these fluxes will be applied.
g :: [in] The ocean’s grid structure.
us :: [in] A dimensional unit scaling type
rho0 :: [in] The mean ocean density [R ~> kg m-3]
cs :: The control structure returned by a previous call to call_tracer_register.

subroutine mom_tracer_flow_control/call_tracer_column_fns(h_old, h_new, ea, eb, fluxes, mld, dt, G, GV, US, tv, optics, CS, debug, KPP_CSp, nonLocalTrans, evap_CFL_limit, minimum_forcing_depth, h_BL)¶

This subroutine calls all registered tracer column physics subroutines.

Parameters

g :: [in] The ocean’s grid structure.
gv :: [in] The ocean’s vertical grid structure.
h_old :: [in] Layer thickness before entrainment [H ~> m or kg m-2].
h_new :: [in] Layer thickness after entrainment [H ~> m or kg m-2].
ea :: [in] an array to which the amount of fluid entrained from the layer above during this call will be added [H ~> m or kg m-2].
eb :: [in] an array to which the amount of fluid entrained from the layer below during this call will be added [H ~> m or kg m-2].
fluxes :: [in] A structure containing pointers to any possible forcing fields. Unused fields have NULL ptrs.
mld :: [in] Mixed layer depth [Z ~> m]
dt :: [in] The amount of time covered by this call [T ~> s]
us :: [in] A dimensional unit scaling type
tv :: [in] A structure pointing to various thermodynamic variables.
optics :: The structure containing optical properties.
cs :: The control structure returned by a previous call to call_tracer_register.
debug :: [in] If true calculate checksums
kpp_csp :: KPP control structure
nonlocaltrans :: [in] Non-local transport [nondim]
evap_cfl_limit :: [in] Limit on the fraction of the water that can be fluxed out of the top layer in a timestep [nondim]
minimum_forcing_depth :: [in] The smallest depth over which fluxes can be applied [H ~> m or kg m-2]
h_bl :: Thickness of active mixing layer [H ~> m or kg m-2]

subroutine mom_tracer_flow_control/call_tracer_stocks(h, stock_values, G, GV, US, CS, stock_names, stock_units, num_stocks, stock_index, got_min_max, global_min, global_max, xgmin, ygmin, zgmin, xgmax, ygmax, zgmax)¶

This subroutine calls all registered tracer packages to enable them to add to the surface state returned to the coupler. These routines are optional.

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]
stock_values :: [out] The globally mass-integrated amount of a tracer [kg conc].
us :: [in] A dimensional unit scaling type
cs :: The control structure returned by a previous call to call_tracer_register.
stock_names :: [out] Diagnostic names to use for each stock.
stock_units :: [out] Units to use in the metadata for each stock.
num_stocks :: [out] The number of tracer stocks being returned.
stock_index :: [in] The integer stock index from stocks_constants_mod of the stock to be returned. If this is present and greater than 0, only a single stock can be returned.
got_min_max :: [inout] Indicates whether the global min and
global_min :: [out] The global minimum of each tracer [conc]
global_max :: [out] The global maximum of each tracer [conc]
xgmin :: [out] The x-position of the global minimum in the units of GgeoLonT, often [degrees_E] or [km]
ygmin :: [out] The y-position of the global minimum in the units of GgeoLatT, often [degrees_N] or [km]
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]
ygmax :: [out] The y-position of the global maximum in the units of GgeoLatT, often [degrees_N] or [km]
zgmax :: [out] The z-position of the global maximum [layer]

Call to

store_stocks

subroutine mom_tracer_flow_control/store_stocks(pkg_name, ns, names, units, values, index, stock_values, set_pkg_name, max_ns, ns_tot, stock_names, stock_units)¶

This routine stores the stocks and does error handling for call_tracer_stocks.

Parameters

pkg_name :: [in] The tracer package name
ns :: [in] The number of stocks associated with this tracer package
names :: [in] Diagnostic names to use for each stock.
units :: [in] Units to use in the metadata for each stock.
values :: [in] The values of the tracer stocks [conc kg]
index :: [in] The integer stock index from stocks_constants_mod of the stock to be returned. If this is present and greater than 0, only a single stock can be returned.
stock_values :: [inout] The master list of stock values [conc kg]
set_pkg_name :: [inout] The name of the last tracer package whose stocks were stored for a specific index. This is used to trigger an error if there are redundant stocks.
max_ns :: [in] The maximum size of the master stock list
ns_tot :: [inout] The total number of stocks in the master list
stock_names :: [inout] Diagnostic names to use for each stock in the master list
stock_units :: [inout] Units to use in the metadata for each stock in the master list

Called from

call_tracer_stocks

subroutine mom_tracer_flow_control/call_tracer_surface_state(sfc_state, h, G, GV, US, CS)¶

This subroutine calls all registered tracer packages to enable them to add to the surface state returned to the coupler. These routines are optional.

Parameters

sfc_state :: [inout] A structure containing fields that describe the surface state of the ocean.
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]
us :: [in] A dimensional unit scaling type
cs :: The control structure returned by a previous call to call_tracer_register.

subroutine mom_tracer_flow_control/tracer_flow_control_end(CS)¶

Parameters: cs :: The control structure returned by a previous call to call_tracer_register.