mom_offline_main module reference

The routines here implement the offline tracer algorithm used in MOM6. These are called from step_offline Some routines called here can be found in the MOM_offline_aux module.

More…

Data Types

offline_transport_cs

The control structure for the offline transport module.

Functions/Subroutines

offline_advection_ale()

3D advection is done by doing flux-limited nonlinear horizontal advection interspersed with an ALE regridding/remapping step. The loop in this routine is exited if remaining residual transports are below a runtime-specified value or a maximum number of iterations is reached.

offline_redistribute_residual()

In the case where the main advection routine did not converge, something needs to be done with the remaining transport.

remaining_transport_sum()

Sums any non-negligible remaining transport to check for advection convergence.

offline_diabatic_ale()

The vertical/diabatic driver for offline tracers.

offline_fw_fluxes_into_ocean()

Apply positive freshwater fluxes (into the ocean) and update netMassOut with only the negative (out of the ocean) fluxes.

offline_fw_fluxes_out_ocean()

Apply negative freshwater fluxes (out of the ocean)

offline_advection_layer()

When in layer mode, 3D horizontal advection using stored mass fluxes must be used.

update_offline_fields()

Update fields used in this round of offline transport.

register_diags_offline_transport()

Initialize additional diagnostics required for offline tracer transport.

post_offline_convergence_diags()

Posts diagnostics related to offline convergence diagnostics.

extract_offline_main()

Extracts members of the offline main control structure.

insert_offline_main()

Inserts (assigns values to) members of the offline main control structure.

offline_transport_init()

Initializes the control structure for offline transport and reads in some of the.

read_all_input()

Coordinates the allocation and reading in all time levels of uh, vh, hend, temp, and salt from files.

offline_transport_end()

Deallocates (if necessary) arrays within the offline control structure.

Detailed Description

Offline Tracer Transport in MOM6

‘Offline tracer modeling’ uses physical fields (e.g. mass transports and layer thicknesses) saved from a previous integration of the physical model to transport passive tracers. These fields are accumulated or averaged over a period of time (in this test case, 1 day) and used to integrate portions of the MOM6 code base that handle the 3d advection and diffusion of passive tracers.

The distribution of tracers in the ocean modeled offline should not be expected to match an online simulation. Accumulating transports over more than one online model timestep implicitly assumes homogeneity over that time period and essentially aliases over processes that occur with higher frequency. For example, consider the case of a surface boundary layer with a strong diurnal cycle. An offline simulation with a 1 day timestep, captures the net transport into or out of that layer, but not the exact cycling. This effective aliasing may also complicate online model configurations which strongly-eddying regions. In this case, the offline model timestep must be limited to some fraction of the eddy correlation timescale. Lastly, the nonlinear advection scheme which applies limited mass-transports over a sequence of iterations means that tracers are not transported along exactly the same path as they are in the online model.

This capability has currently targeted the Baltic_ALE_z test case, though some work has also been done with the OM4 1/2 degree configuration. Work is ongoing to develop recommendations and best practices for investigators seeking to use MOM6 for offline tracer modeling.

Implementation of offline routine in MOM6

The subroutine step_tracers that coordinates this can be found in MOM.F90 and is only called using the solo ocean driver. This is to avoid issues with coupling to other climate components that may be relying on fluxes from the ocean to be coupled more often than the offline time step. Other routines related to offline tracer modeling can be found in tracers/MOM_offline_control.F90

As can also be seen in the comments for the step_tracers subroutine, an offline time step comprises the following steps: #. Using the layer thicknesses and tracer concentrations from the previous timestep, half of the accumulated vertical mixing (eatr and ebtr) is applied in the call to tracer_column_fns. For tracers whose source/sink terms need dt, this value is set to 1/2 dt_offline

  1. Half of the accumulated surface freshwater fluxes are applied START ITERATION

  2. Accumulated mass fluxes are used to do horizontal transport. The number of iterations used in advect_tracer is limited to 2 (e.g x->y->x->y). The remaining mass fluxes are stored for later use and resulting layer thicknesses fed into the next step

  3. Tracers and the h-grid are regridded and remapped in a call to ALE. This allows for layers which might ‘vanish’ because of horizontal mass transport to be ‘reinflated’ and essentially allows for the vertical transport of tracers

  4. Check that transport is done if the remaining mass fluxes equals 0 or if the max number of iterations has been reached END ITERATION

  5. Repeat steps 1 and 2

  6. Redistribute any residual mass fluxes that remain after the advection iterations in a barotropic manner, progressively upward through the water column.

  7. Force a remapping to the stored layer thicknesses that correspond to the snapshot of the online model at the end of an accumulation interval

  8. Reset T/S and h to their stored snapshotted values to prevent model drift

Evaluating the utility of an offline tracer model

How well an offline tracer model can be used as an alternative to integrating tracers online with the prognostic model must be evaluated for each application. This efficacy may be related to the native coordinate of the online model, to the length of the offline timestep, and to the behavior of the tracer itself.

A framework for formally regression testing the offline capability still needs to be developed. However, as a simple way of testing whether the offline model is nominally behaving as expected, the total inventory of the advection test tracers (tr1, tr2, etc.) should be conserved between time steps except for the last 4 decimal places. As a general guideline, an offline timestep of 5 days or less.

Runtime parameters for offline tracers

  • OFFLINEDIR: Input directory where the offline fields can be found

  • OFF_SUM_FILE: Filename where the accumulated fields can be found (e.g. horizontal mass transports)

  • OFF_SNAP_FILE: Filename where snapshot fields can be found (e.g. end of timestep layer thickness)

  • START_INDEX: Which timelevel of the input files to read first

  • NUMTIME: How many timelevels to read before ‘looping’ back to 1

  • FIELDS_ARE_OFFSET: True if the time-averaged fields and snapshot fields are offset by one time level, probably not needed -NUM_OFF_ITER: Maximum number of iterations to do for the nonlinear advection scheme -REDISTRIBUTE_METHOD: Redistributes any remaining horizontal fluxes throughout the rest of water column. Options are ‘barotropic’ which “evenly distributes flux throughout the entire water column,’upwards’ which adds the maximum of the remaining flux in each layer above, and ‘none’ which does no redistribution”

Type Documentation

type mom_offline_main/offline_transport_cs

The control structure for the offline transport module.

Type fields
  • % id_uhr [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_vhr [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_ear [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_ebr [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_hr [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_hdiff [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_uhr_redist [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_vhr_redist [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_uhr_end [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_vhr_end [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_eta_pre_distribute [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_eta_post_distribute [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_h_redist [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_eta_diff_end [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_uhtr_regrid [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_vhtr_regrid [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_temp_regrid [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_salt_regrid [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % id_h_regrid [integer] :: Diagnostic manager IDs for some fields that may be of interest when doing offline transport.

  • % ale_csp [type(ale_cs),pointer] :: A pointer to the ALE control structure.

  • % diabatic_csp [type(diabatic_cs),pointer] :: A pointer to the diabatic control structure.

  • % diag [type(diag_ctrl),pointer] :: Structure that regulates diagnostic output.

  • % obc [type(ocean_obc_type),pointer] :: A pointer to the open boundary condition control structure.

  • % tracer_adv_csp [type(tracer_advect_cs),pointer] :: A pointer to the tracer advection control structure.

  • % opacity_csp [type(opacity_cs),pointer] :: A pointer to the opacity control structure.

  • % tracer_flow_csp [type(tracer_flow_control_cs),pointer] :: A pointer to control structure that orchestrates the calling of tracer packages.

  • % tracer_reg [type(tracer_registry_type),pointer] :: A pointer to the tracer registry.

  • % tv [type(thermo_var_ptrs),pointer] :: A structure pointing to various thermodynamic variables.

  • % g [type(ocean_grid_type),pointer] :: Pointer to a structure containing metrics and related information.

  • % gv [type(verticalgrid_type),pointer] :: Pointer to structure containing information about the vertical grid.

  • % us [type(unit_scale_type),pointer] :: structure containing various unit conversion factors

  • % optics [type(optics_type),pointer] :: Pointer to the optical properties type.

  • % diabatic_aux_csp [type(diabatic_aux_cs),pointer] :: Pointer to the diabatic_aux control structure.

  • % start_index [integer] :: Variables related to reading in fields from online run.

  • % iter_no [integer] :: Timelevel to start.

  • % numtime [integer] :: How many timelevels in the input fields.

  • % accumulated_time [type(time_type)] :: Length of time accumulated in the current offline interval.

  • % vertical_time [type(time_type)] :: The next value of accumulate_time at which to apply vertical processes.

  • % ridx_sum [integer] :: Read index offset of the summed variables.

  • % ridx_snap [integer] :: Read index offset of the snapshot variables.

  • % nk_input [integer] :: Number of input levels in the input fields.

  • % offlinedir [character (len=200)] :: Directory where offline fields are stored.

  • % surf_file [character (len=200)] :: Contains surface fields (2d arrays)

  • % snap_file [character (len=200)] :: Snapshotted fields (layer thicknesses)

  • % sum_file [character (len=200)] :: Fields which are accumulated over time.

  • % mean_file [character (len=200)] :: Fields averaged over time.

  • % redistribute_method [character (len=20)] :: ‘barotropic’ if evenly distributing extra flow throughout entire watercolumn, ‘upwards’, if trying to do it just in the layers above ‘both’ if both methods are used

  • % mld_var_name [character (len=20)] :: Name of the mixed layer depth variable to use.

  • % fields_are_offset [logical] :: True if the time-averaged fields and snapshot fields are offset by one time level.

  • % x_before_y [logical] :: Which horizontal direction is advected first.

  • % print_adv_offline [logical] :: Prints out some updates each advection sub interation.

  • % skip_diffusion [logical] :: Skips horizontal diffusion of tracers.

  • % read_sw [logical] :: Read in averaged values for shortwave radiation.

  • % read_mld [logical] :: Check to see whether mixed layer depths should be read in.

  • % diurnal_sw [logical] :: Adds a synthetic diurnal cycle on shortwave radiation.

  • % debug [logical] :: If true, write verbose debugging messages.

  • % redistribute_barotropic [logical] :: Redistributes column-summed residual transports throughout a column weighted by thickness.

  • % redistribute_upwards [logical] :: Redistributes remaining fluxes only in layers above the current one based as the max allowable transport in that cell.

  • % read_all_ts_uvh [logical] :: If true, then all timelevels of temperature, salinity, mass transports, and Layer thicknesses are read during initialization Variables controlling some of the numerical considerations of offline transport.

  • % num_off_iter [integer] :: Number of advection iterations per offline step.

  • % num_vert_iter [integer] :: Number of vertical iterations per offline step.

  • % off_ale_mod [integer] :: Sets how frequently the ALE step is done during the advection.

  • % dt_offline [real] :: Timestep used for offline tracers [T ~> s].

  • % dt_offline_vertical [real] :: Timestep used for calls to tracer vertical physics [T ~> s].

  • % evap_cfl_limit [real] :: Limit on the fraction of the water that can be fluxed out of the top layer in a timestep [nondim]. This is Copied from diabatic_CS controlling how tracers follow freshwater fluxes.

  • % minimum_forcing_depth [real] :: The smallest depth over which fluxes can be applied [H ~> m or kg m-2]. This is copied from diabatic_CS controlling how tracers follow freshwater fluxes.

  • % kd_max [real] :: Runtime parameter specifying the maximum value of vertical diffusivity.

  • % min_residual [real] :: The minimum amount of total mass flux before exiting the main advection routine.

  • % id_clock_read_fields [integer] :: A CPU time clock.

  • % id_clock_offline_diabatic [integer] :: A CPU time clock.

  • % id_clock_offline_adv [integer] :: A CPU time clock.

  • % id_clock_redistribute [integer] :: A CPU time clock.

  • % uhtr [real(:,:,:),allocatable] :: Zonal transport that may need to be stored between calls to step_MOM.

  • % vhtr [real(:,:,:),allocatable] :: Meridional transport that may need to be stored between calls to step_MOM.

  • % eatr [real(:,:,:),allocatable] :: Amount of fluid entrained from the layer above within one time step [H ~> m or kg m-2].

  • % ebtr [real(:,:,:),allocatable] :: Amount of fluid entrained from the layer below within one time step [H ~> m or kg m-2].

  • % kd [real(:,:,:),allocatable] :: Vertical diffusivity.

  • % h_end [real(:,:,:),allocatable] :: Thicknesses at the end of offline timestep.

  • % netmassin [real(:,:),allocatable] :: Freshwater fluxes into the ocean.

  • % netmassout [real(:,:),allocatable] :: Freshwater fluxes out of the ocean.

  • % mld [real(:,:),allocatable] :: Mixed layer depths at thickness points [Z ~> m].

  • % uhtr_all [real(:,:,:,:),allocatable] :: Entire field of zonal transport.

  • % vhtr_all [real(:,:,:,:),allocatable] :: Entire field of mericional transport.

  • % hend_all [real(:,:,:,:),allocatable] :: Entire field of layer thicknesses.

  • % temp_all [real(:,:,:,:),allocatable] :: Entire field of temperatures.

  • % salt_all [real(:,:,:,:),allocatable] :: Entire field of salinities.

Function/Subroutine Documentation

subroutine mom_offline_main/offline_advection_ale(fluxes, Time_start, time_interval, CS, id_clock_ale, h_pre, uhtr, vhtr, converged)

3D advection is done by doing flux-limited nonlinear horizontal advection interspersed with an ALE regridding/remapping step. The loop in this routine is exited if remaining residual transports are below a runtime-specified value or a maximum number of iterations is reached.

Parameters
  • fluxes :: [inout] pointers to forcing fields

  • time_start :: [in] starting time of a segment, as a time type

  • time_interval :: [in] time interval

  • cs :: control structure for offline module

  • id_clock_ale :: [in] Clock for ALE routines

  • h_pre :: [inout] layer thicknesses before advection

  • uhtr :: [inout] Zonal mass transport [H m2 ~> m3 or kg]

  • vhtr :: [inout] Meridional mass transport [H m2 ~> m3 or kg]

  • converged :: [out] True if the iterations have converged

Call to

mom_tracer_advect::advect_tracer mom_ale::ale_main_offline mom_tracer_registry::mom_tracer_chkinv remaining_transport_sum

subroutine mom_offline_main/offline_redistribute_residual(CS, h_pre, uhtr, vhtr, converged)

In the case where the main advection routine did not converge, something needs to be done with the remaining transport. Two different ways are offered, ‘barotropic’ means that the residual is distributed equally throughout the water column. ‘upwards’ attempts to redistribute the transport in the layers above and will eventually work down the entire water column.

Parameters
  • cs :: control structure from initialize_MOM

  • h_pre :: [inout] layer thicknesses before advection

  • uhtr :: [inout] Zonal mass transport

  • vhtr :: [inout] Meridional mass transport

  • converged :: [in] True if the iterations have converged

Call to

mom_tracer_advect::advect_tracer mom_offline_aux::distribute_residual_uh_upwards mom_offline_aux::distribute_residual_vh_upwards mom_tracer_registry::mom_tracer_chkinv mom_tracer_registry::mom_tracer_chksum remaining_transport_sum

function mom_offline_main/remaining_transport_sum(CS, uhtr, vhtr) [real]

Sums any non-negligible remaining transport to check for advection convergence.

Parameters
  • cs :: control structure for offline module

  • uhtr :: [in] Zonal mass transport

  • vhtr :: [in] Meridional mass transport

Called from

offline_advection_ale offline_redistribute_residual

subroutine mom_offline_main/offline_diabatic_ale(fluxes, Time_start, Time_end, CS, h_pre, eatr, ebtr)

The vertical/diabatic driver for offline tracers. First the eatr/ebtr associated with the interpolated vertical diffusivities are calculated and then any tracer column functions are done which can include vertical diffuvities and source/sink terms.

Parameters
  • fluxes :: [inout] pointers to forcing fields

  • time_start :: [in] starting time of a segment, as a time type

  • time_end :: [in] time interval

  • cs :: control structure from initialize_MOM

  • h_pre :: [inout] layer thicknesses before advection [H ~> m or kg m-2]

  • eatr :: [inout] Entrainment from layer above [H ~> m or kg m-2]

  • ebtr :: [inout] Entrainment from layer below [H ~> m or kg m-2]

Call to

mom_tracer_flow_control::call_tracer_column_fns mom_tracer_registry::mom_tracer_chkinv

subroutine mom_offline_main/offline_fw_fluxes_into_ocean(G, GV, CS, fluxes, h, in_flux_optional)

Apply positive freshwater fluxes (into the ocean) and update netMassOut with only the negative (out of the ocean) fluxes.

Parameters
  • cs :: [inout] Offline control structure

  • g :: [in] Grid structure

  • gv :: [in] ocean vertical grid structure

  • fluxes :: [inout] Surface fluxes container

  • h :: [inout] Layer thickness [H ~> m or kg m-2]

  • in_flux_optional :: [in] The total time-integrated amount

Call to

mom_tracer_diabatic::applytracerboundaryfluxesinout mom_tracer_registry::mom_tracer_chkinv

subroutine mom_offline_main/offline_fw_fluxes_out_ocean(G, GV, CS, fluxes, h, out_flux_optional)

Apply negative freshwater fluxes (out of the ocean)

Parameters
  • cs :: [inout] Offline control structure

  • g :: [in] Grid structure

  • gv :: [in] ocean vertical grid structure

  • fluxes :: [inout] Surface fluxes container

  • h :: [inout] Layer thickness [H ~> m or kg m-2]

  • out_flux_optional :: [in] The total time-integrated amount

Call to

mom_tracer_diabatic::applytracerboundaryfluxesinout mom_tracer_registry::mom_tracer_chkinv

subroutine mom_offline_main/offline_advection_layer(fluxes, Time_start, time_interval, CS, h_pre, eatr, ebtr, uhtr, vhtr)

When in layer mode, 3D horizontal advection using stored mass fluxes must be used. Horizontal advection is done via tracer_advect, whereas the vertical component is actually handled by vertdiff in tracer_column_fns.

Parameters
  • fluxes :: [inout] pointers to forcing fields

  • time_start :: [in] starting time of a segment, as a time type

  • time_interval :: [in] Offline transport time interval

  • cs :: Control structure for offline module

  • h_pre :: [inout] layer thicknesses before advection

  • eatr :: [inout] Entrainment from layer above

  • ebtr :: [inout] Entrainment from layer below

  • uhtr :: [inout] Zonal mass transport

  • vhtr :: [inout] Meridional mass transport

Call to

mom_tracer_advect::advect_tracer mom_tracer_flow_control::call_tracer_column_fns

subroutine mom_offline_main/update_offline_fields(CS, h, fluxes, do_ale)

Update fields used in this round of offline transport. First fields are updated from files or from arrays read during initialization. Then if in an ALE-dependent coordinate, regrid/remap fields.

Parameters
  • cs :: Control structure for offline module

  • h :: The regridded layer thicknesses

  • fluxes :: [inout] Pointers to forcing fields

  • do_ale :: [in] True if using ALE

Call to

mom_ale::ale_offline_inputs mom_error_handler::calltree_enter mom_error_handler::calltree_leave

subroutine mom_offline_main/register_diags_offline_transport(Time, diag, CS)

Initialize additional diagnostics required for offline tracer transport.

Parameters
  • cs :: Control structure for offline module

  • time :: [in] current model time

  • diag :: [in] Structure that regulates diagnostic output

Call to

mom_diag_mediator::register_diag_field

subroutine mom_offline_main/post_offline_convergence_diags(CS, h_off, h_end, uhtr, vhtr)

Posts diagnostics related to offline convergence diagnostics.

Parameters
  • cs :: [in] Offline control structure

  • h_off :: [inout] Thicknesses at end of offline step

  • h_end :: [inout] Stored thicknesses

  • uhtr :: [inout] Remaining zonal mass transport

  • vhtr :: [inout] Remaining meridional mass transport

subroutine mom_offline_main/extract_offline_main(CS, uhtr, vhtr, eatr, ebtr, h_end, accumulated_time, vertical_time, dt_offline, dt_offline_vertical, skip_diffusion)

Extracts members of the offline main control structure. All arguments are optional except the control structure itself.

Parameters
  • cs :: [in] Offline control structure

  • uhtr :: Remaining zonal mass transport [H m2 ~> m3 or kg]

  • vhtr :: Remaining meridional mass transport [H m2 ~> m3 or kg]

  • eatr :: Amount of fluid entrained from the layer above within one time step [H ~> m or kg m-2]

  • ebtr :: Amount of fluid entrained from the layer below within one time step [H ~> m or kg m-2]

  • h_end :: Thicknesses at the end of offline timestep [H ~> m or kg m-2]

  • accumulated_time :: Length of time accumulated in the current offline interval

  • vertical_time :: The next value of accumulate_time at which to vertical processes

  • dt_offline :: [out] Timestep used for offline tracers [T ~> s]

  • dt_offline_vertical :: [out] Timestep used for calls to tracer vertical physics [T ~> s]

  • skip_diffusion :: [out] Skips horizontal diffusion of tracers

subroutine mom_offline_main/insert_offline_main(CS, ALE_CSp, diabatic_CSp, diag, OBC, tracer_adv_CSp, tracer_flow_CSp, tracer_Reg, tv, G, GV, x_before_y, debug)

Inserts (assigns values to) members of the offline main control structure. All arguments are optional except for the CS itself.

Parameters
  • cs :: [inout] Offline control structure

  • ale_csp :: [in] A pointer to the ALE control structure

  • diabatic_csp :: [in] A pointer to the diabatic control structure

  • diag :: [in] A pointer to the structure that regulates diagnostic output

  • obc :: [in] A pointer to the open boundary condition control structure

  • tracer_adv_csp :: [in] A pointer to the tracer advection control structure

  • tracer_flow_csp :: [in] A pointer to the tracer flow control control structure

  • tracer_reg :: [in] A pointer to the tracer registry

  • tv :: [in] A structure pointing to various thermodynamic variables

  • g :: [in] ocean grid structure

  • gv :: [in] ocean vertical grid structure

  • x_before_y :: [in] Indicates which horizontal direction is advected first

  • debug :: [in] If true, write verbose debugging messages

subroutine mom_offline_main/offline_transport_init(param_file, CS, diabatic_CSp, G, GV, US)

Initializes the control structure for offline transport and reads in some of the.

Parameters
  • param_file :: [in] A structure to parse for run-time parameters

  • cs :: Offline control structure

  • diabatic_csp :: [in] The diabatic control structure

  • g :: [in] ocean grid structure

  • gv :: [in] ocean vertical grid structure

  • us :: [in] A dimensional unit scaling type

Call to

mom_error_handler::calltree_enter mom_error_handler::calltree_leave mom_diabatic_driver::extract_diabatic_member read_all_input

subroutine mom_offline_main/read_all_input(CS)

Coordinates the allocation and reading in all time levels of uh, vh, hend, temp, and salt from files. Used when read_all_ts_uvh.

Parameters

cs :: [inout] Control structure for offline module

Called from

offline_transport_init

subroutine mom_offline_main/offline_transport_end(CS)

Deallocates (if necessary) arrays within the offline control structure.

Parameters

cs :: Control structure for offline module