Contact:  Richard D. Slater
Reviewers:  Stephen M. Griffies
Change History: WebCVS Log

This module is a superset of the ocean age tracer module. It may be used to reproduce the age tracer, but it can also do much more. Unlike the ocean age tracer module, here you may specify a 3-d field by specifying a series of "rectangular prisms". The grid cells which occupy this field may vary with time due to the variations in the thickness of the surface layer.

You may also specify a 3-d field by choosing one of three mixed-layers (KPP, density-derived or buoyancy-derived). You may also specify a region based on a a range of a prognostic or diagnostic ocean tracer (such as all points with a temperature of 10-20 degrees).

You may specify either the mixed-layer method or the tracer range along with the geographic specification. If multiple methods are used, then the resultant field is the intersection of the two methods. In fact, the geographic method is always in use, and defaults to the whole ocean.

There is an option of using the inverse of any method. This is sometimes easier to use than explicitly specifying the inverse. For instance, to get the temperatures outside of the range 10-20 degrees, one could specify the 10-20 degree range and set <swap> to true, or, specify two different regions, one less than 10 degrees and one greater than 20 degrees.

By default, the values inside the specified region are set to a specified value each time-step (default is 0), and outside of this region the field is integrated over time in units of years (integrand is 1/(365.25*86400) by default, but this value can be changed. The inner region can be forced to be 0 (or the user-specified inner value) at each time-step (the default), or it can be restored to this value at a user-specified rate (given in days), or, it can be left alone (not integrated or set to any value).

Finally, since we are just integrating a specified field by a constant value (by default), it is simple to make that field a simple function of another tracer. This is the final option. You may specify a prognostic or diagnostic variable to be the integrand, and have it scaled by a constant. One case which has been done is to integrate irradiance in the mixed-layer.

This module is split into several different modules. This particular module is the only one called from outside, and it makes appropriate calls to the other modules to implement its features. This was done so that it would be easier to expand the features of the ocean residency, without cluttering the code too much. Ideally, this could all be done with classes, but there is currently no support for classes in Fortran (pre-F2003). The current modules are:

ocean_residency.F90 This module, the control center, and also does the integrations and resetting in the inner regions. ocean_residency_meta.F90 Has specifications of the ocean_residency type and other utility routines. This is separate to stop circular references ocean_residency_ml.F90 Handles setting mixed-layer masks ocean_residency_range.F90 Handles setting the masks for the tracer ranges ocean_residency_integrand.F90 Handles setting the integrand to a non-constant value

field_table namelist inputs:

The following 6 arrays specify the bounds of boxes, the intersection of which will define the region where the integrand is set to restore_region_value. ALl arrays must have the same number of elements. If none are specified, then no region will be used, unless swap is true, which is a quick way of selecting the entire ocean. This may be useful when one really wants to use one of the other methods of selecting, such as mixed layer depth, or tracer range.

Longitudes will be shifted to lie in the range 0-360 degrees. If the eastern side is greater than the western, then the selected region will consist of those grid cells from the eastern value to 360, and 0 to the western value. If the northern value is less than the southern value, or if the top depth is greater than the bottom depth, then an error occurs, and the model stops.

Three special cases exist for the depth (which currently must be in meters). If the bottom value is less than or equal to zero, then the top box is selected. If the top value is greater than the maximum depth, then the bottom box is selected. If the top value is negative, then grid cells within "the absolute value of the top value" from the bottom are selected.

Note that the geographic specification is used for all residency tracers, so either values for these 6 arrays must be given so as to select a region, or else swap must be set to true and no arrays given.

east_bnd: array of boundary points of the eastern side of the box, in degrees longitude (default: NULL) north_bnd: array of boundary points of the northern side of the box, in degrees latitude (default: NULL) south_bnd: array of boundary points of the southern side of the box, in degrees latitude (default: NULL) west_bnd: array of boundary points of the western side of the box, in degrees longitude (default: NULL) top_bnd: array of boundary points of the top side of the box, in meters (default: NULL) bottom_bnd: array of boundary points of the bottom side of the box, in meters (default: NULL)

swap: if true, then select the inverse of the specified geographic region, otherwise, just use the specified region (default: false) restore: restoring value for values in the defined regions negative => do nothing, 0 => force to integrate_region_value, positive => time scale in days to force to integrate_region_value (default: 0.0) restore_region_value: value to set the mask to for grid cells within the specified region (default: 0.0) integrate_region_value: value to set the mask to for grid cells outside the specified region (default: secs_in_year_r) swap_module: if true, then select the inverse of the region from the specified module, otherwise, just use the specified region (default: false) module_name: if set, then it will be used to select the alternate method of selecting the region (default: ' ' -- only geographic selection is used)

For the following arrays, see the different extra modules for required and possible values for the module selected.

params: an array of real parameters which may be used for the method being used for selection (default: NULL) flags: an array of real parameters which may be used for the method being used for selection (default: NULL) strings: an array of real parameters which may be used for the method being used for selection (default: NULL)

For the following arrays, see the different extra modules for required and possible values for the module selected to specify the integrand. int_module_name: if set, then the name of the module used to set the integrand (default: ' ' -- integrate time, in years) int_params: an array of real parameters which may be used for the integrand (default: NULL) int_flags: an array of real parameters which may be used for the integrand (default: NULL) int_strings: an array of real parameters which may be used for the integrand (default: NULL)

----------------------------------------------------------------------------------------

Sample field table entries: ---------------------------

"tracer_packages","ocean_mod","ocean_residency" names = age_surface, age_bottom_inv, kppbl_nil, kppbl_14d, kppbl_frc, kppbl_irr_14d, temp_15_20 horizontal-advection-scheme = mdppm vertical-advection-scheme = mdppm units = yr min_tracer_limit=0.0 /

This is the same as the old age tracer with all surface values forced to zero

"namelists","ocean_mod","ocean_residency/age_surface" south_bnd = -90.0 north_bnd = 90.0 west_bnd = 0.0 east_bnd = 360.0 top_bnd = 0.0 bottom_bnd = 0.0 /

This integrates the age in the bottom box and forces to zero everywhere else (note that swap is true)

"namelists","ocean_mod","ocean_residency/age_bottom_inv" south_bnd = -90.0 north_bnd = 90.0 west_bnd = 0.0 east_bnd = 360.0 top_bnd = 10000.0 bottom_bnd = 10000.0 swap = t /

This integrates the age of the water in the KPP boundary layer, but lets the age outside of this region keep its value until it again mixes with the boundary layer. The module_name is set, and strings is set to pick the type of mixed layer desired (note that the global geographic area is explicitly specified, and that the restoring time scale is negative)

"namelists","ocean_mod","ocean_residency/kppbl_nil" south_bnd = -90.0 north_bnd = 90.0 west_bnd = 0.0 east_bnd = 360.0 top_bnd = 0.0 bottom_bnd = 10000.0 restore = -1.0 module_name = ocean_residency_ml strings = kpp_bl swap_module = t /

This is the same as above, but forces the age outside the boundary layer to 0 with a 14 day time scale (note that the global geographic region is specified by setting swap to true, also note the value of restore)

"namelists","ocean_mod","ocean_residency/kppbl_14d" swap = t restore = 14.0 module_name = ocean_residency_ml strings = kpp_bl swap_module = t /

This is the same as above, but forces age to zero outside the boundary layer (note that restore did not need to be explicitly specified, as the default is zero)

"namelists","ocean_mod","ocean_residency/kppbl_frc" swap = t restore = 0.0 module_name = ocean_residency_ml strings = kpp_bl swap_module = t /

The following integrates irradiance in the boundary layer (note that the units needed to be changed for netCDF output purposes)

"prog_tracers","ocean_mod","residency_kppbl_irr_14d" units = W-yr/m^2 /

"namelists","ocean_mod","ocean_residency/kppbl_irr_14d" swap = t restore = 14.0 module_name = ocean_residency_ml strings = kpp_bl swap_module = t int_module_name = ocean_residency_integrand int_strings = irr /

This specifies the region as the area with a temperature range of between 15 and 20 degrees (note that the params holds the variable range)

"namelists","ocean_mod","ocean_residency/temp_15_20" swap = t module_name = ocean_residency_range strings = tracer_range, temp params = 15.0, 20.0 /

             time_manager_mod
            field_manager_mod
                      mpp_mod
             diag_manager_mod
           ocean_tpm_util_mod
                  fm_util_mod
              ocean_types_mod
     ocean_residency_meta_mod
       ocean_residency_ml_mod
    ocean_residency_range_mod
ocean_residency_integrand_mod

ocean_residency_init:

ocean_residency_source:

ocean_residency_start:

ocean_residency_tracer:

None.

None.

None.

top