namespace mom_offline_main

Overview

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…

namespace mom_offline_main {

// global functions

subroutine, public offline_advection_ale(
    fluxes fluxes,
    Time_start Time_start,
    time_interval time_interval,
    CS CS,
    id_clock_ale id_clock_ale,
    h_pre h_pre,
    uhtr uhtr,
    vhtr vhtr,
    converged converged
    );

subroutine, public offline_redistribute_residual(
    CS CS,
    h_pre h_pre,
    uhtr uhtr,
    vhtr vhtr,
    converged converged
    );

subroutine, public offline_diabatic_ale(
    fluxes fluxes,
    Time_start Time_start,
    Time_end Time_end,
    CS CS,
    h_pre h_pre,
    eatr eatr,
    ebtr ebtr
    );

subroutine, public offline_fw_fluxes_into_ocean(
    G G,
    GV GV,
    CS CS,
    fluxes fluxes,
    h h,
    in_flux_optional in_flux_optional
    );

subroutine, public offline_fw_fluxes_out_ocean(
    G G,
    GV GV,
    CS CS,
    fluxes fluxes,
    h h,
    out_flux_optional out_flux_optional
    );

subroutine, public offline_advection_layer(
    fluxes fluxes,
    Time_start Time_start,
    time_interval time_interval,
    CS CS,
    h_pre h_pre,
    eatr eatr,
    ebtr ebtr,
    uhtr uhtr,
    vhtr vhtr
    );

subroutine, public update_offline_fields(CS CS, h h, fluxes fluxes, do_ale do_ale);
subroutine, public register_diags_offline_transport(Time Time, diag diag, CS CS);
subroutine, public post_offline_convergence_diags(CS CS, h_off h_off, h_end h_end, uhtr uhtr, vhtr vhtr);

subroutine, public extract_offline_main(
    CS CS,
    uhtr uhtr,
    vhtr vhtr,
    eatr eatr,
    ebtr ebtr,
    h_end h_end,
    accumulated_time accumulated_time,
    dt_offline dt_offline,
    dt_offline_vertical dt_offline_vertical,
    skip_diffusion skip_diffusion
    );

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

subroutine, public offline_transport_init(
    param_file param_file,
    CS CS,
    diabatic_CSp diabatic_CSp,
    G G,
    GV GV,
    US US
    );

subroutine, public offline_transport_end(CS CS);

} // namespace mom_offline_main

Detailed Documentation

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.

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:

1. 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

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

3. 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

4. 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

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

6. Repeat steps 1 and 2

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

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

9. 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”

Global Functions

subroutine, public offline_advection_ale(
    fluxes fluxes,
    Time_start Time_start,
    time_interval time_interval,
    CS CS,
    id_clock_ale id_clock_ale,
    h_pre h_pre,
    uhtr uhtr,
    vhtr vhtr,
    converged 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	pointers to forcing fields
time_start	starting time of a segment, as a time type
time_interval	time interval
cs	control structure for offline module
id_clock_ale	Clock for ALE routines
h_pre	layer thicknesses before advection
uhtr	Zonal mass transport [H m2 ~> m3 or kg]
vhtr	Meridional mass transport [H m2 ~> m3 or kg]
converged	True if the iterations have converged

subroutine, public offline_redistribute_residual(
    CS CS,
    h_pre h_pre,
    uhtr uhtr,
    vhtr vhtr,
    converged 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	layer thicknesses before advection
uhtr	Zonal mass transport
vhtr	Meridional mass transport
converged	True if the iterations have converged

subroutine, public offline_diabatic_ale(
    fluxes fluxes,
    Time_start Time_start,
    Time_end Time_end,
    CS CS,
    h_pre h_pre,
    eatr eatr,
    ebtr 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	pointers to forcing fields
time_start	starting time of a segment, as a time type
time_end	time interval
cs	control structure from initialize_MOM
h_pre	layer thicknesses before advection [H ~> m or kg m-2]
eatr	Entrainment from layer above [H ~> m or kg m-2]
ebtr	Entrainment from layer below [H ~> m or kg m-2]

subroutine, public offline_fw_fluxes_into_ocean(
    G G,
    GV GV,
    CS CS,
    fluxes fluxes,
    h h,
    in_flux_optional in_flux_optional
    )

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

Parameters:

cs	Offline control structure
g	Grid structure
gv	ocean vertical grid structure
fluxes	Surface fluxes container
h	Layer thickness [H ~> m or kg m-2]
in_flux_optional	The total time-integrated amount

subroutine, public offline_fw_fluxes_out_ocean(
    G G,
    GV GV,
    CS CS,
    fluxes fluxes,
    h h,
    out_flux_optional out_flux_optional
    )

Apply negative freshwater fluxes (out of the ocean)

Parameters:

cs	Offline control structure
g	Grid structure
gv	ocean vertical grid structure
fluxes	Surface fluxes container
h	Layer thickness [H ~> m or kg m-2]
out_flux_optional	The total time-integrated amount

subroutine, public offline_advection_layer(
    fluxes fluxes,
    Time_start Time_start,
    time_interval time_interval,
    CS CS,
    h_pre h_pre,
    eatr eatr,
    ebtr ebtr,
    uhtr uhtr,
    vhtr 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	pointers to forcing fields
time_start	starting time of a segment, as a time type
time_interval	Offline transport time interval
cs	Control structure for offline module
h_pre	layer thicknesses before advection
eatr	Entrainment from layer above
ebtr	Entrainment from layer below
uhtr	Zonal mass transport
vhtr	Meridional mass transport

subroutine, public update_offline_fields(
    CS CS,
    h h,
    fluxes fluxes,
    do_ale 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	Pointers to forcing fields
do_ale	True if using ALE

subroutine, public register_diags_offline_transport(Time Time, diag diag, CS CS)

Initialize additional diagnostics required for offline tracer transport.

Parameters:

cs	Control structure for offline module
time	current model time
diag	Structure that regulates diagnostic output

subroutine, public post_offline_convergence_diags(
    CS CS,
    h_off h_off,
    h_end h_end,
    uhtr uhtr,
    vhtr vhtr
    )

Posts diagnostics related to offline convergence diagnostics.

Parameters:

cs	Offline control structure
h_off	Thicknesses at end of offline step
h_end	Stored thicknesses
uhtr	Remaining zonal mass transport
vhtr	Remaining meridional mass transport

subroutine, public extract_offline_main(
    CS CS,
    uhtr uhtr,
    vhtr vhtr,
    eatr eatr,
    ebtr ebtr,
    h_end h_end,
    accumulated_time accumulated_time,
    dt_offline dt_offline,
    dt_offline_vertical dt_offline_vertical,
    skip_diffusion skip_diffusion
    )

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

Parameters:

cs	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 [s]
dt_offline	Timestep used for offline tracers [s]
dt_offline_vertical	Timestep used for calls to tracer vertical physics [s]
skip_diffusion	Skips horizontal diffusion of tracers

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

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

Parameters:

cs	Offline control structure
ale_csp	A pointer to the ALE control structure
diabatic_csp	A pointer to the diabatic control structure
diag	A pointer to the structure that regulates diagnostic output
obc	A pointer to the open boundary condition control structure
tracer_adv_csp	A pointer to the tracer advection control structure
tracer_flow_csp	A pointer to the tracer flow control control structure
tracer_reg	A pointer to the tracer registry
tv	A structure pointing to various thermodynamic variables
g	ocean grid structure
gv	ocean vertical grid structure
x_before_y	Indicates which horizontal direction is advected first
debug	If true, write verbose debugging messages

subroutine, public offline_transport_init(
    param_file param_file,
    CS CS,
    diabatic_CSp diabatic_CSp,
    G G,
    GV GV,
    US US
    )

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

Parameters:

param_file	A structure to parse for run-time parameters
cs	Offline control structure
diabatic_csp	The diabatic control structure
g	ocean grid structure
gv	ocean vertical grid structure
us	A dimensional unit scaling type

subroutine, public offline_transport_end(CS CS)

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

Parameters:

cs	Control structure for offline module