PUBLIC INTERFACE ~ PUBLIC DATA ~ PUBLIC ROUTINES ~ NAMELIST ~ DIAGNOSTIC FIELDS ~ ERROR MESSAGES ~ REFERENCES ~ NOTES

Module ocean_barotropic_mod

Contact:  S.M. Griffies (mom4 algorithms) ,  R.C. Pacanowski (mom3 algorithm) ,  Zhi Liang (OBC) ,  Martin Schmidt (OBC) ,  Harper Simmons (tides)
Reviewers:  M.J. Harrison
Change History: WebCVS Log

OVERVIEW

Update the vertically integrated dynamics using a split-explicit algorithm.

This module time steps the vertically integrated dynamics.

Two explicit time stepping schemes are available:

A. Leap-frog with optional Robert-Asselin time filter

B. Predictor-Corrector with adjustable dissipation

Both use a split-explicit method.

There is no rigid lid available in mom4.


OTHER MODULES USED

         constants_mod
      diag_manager_mod
               fms_mod
            fms_io_mod
       mpp_domains_mod
               mpp_mod
      time_manager_mod
ocean_bih_friction_mod
     ocean_domains_mod
ocean_lap_friction_mod
         ocean_obc_mod
   ocean_operators_mod
  ocean_parameters_mod
       ocean_types_mod
        ocean_util_mod
   ocean_workspace_mod

PUBLIC INTERFACE

ocean_barotropic_init:
eta_and_pbot_update:
eta_and_pbot_diagnose:
eta_and_pbot_tendency:
update_ocean_barotropic:
ocean_barotropic_forcing:
ocean_mass_forcing:
leap_frog_barotropic_depth:
pred_corr_barotropic_depth:
pred_corr_barotropic_press:
eta_smooth_diagnosed:
ocean_eta_smooth:
ocean_pbot_smooth:
barotropic_integrals:
barotropic_energy:
read_barotropic:
ocean_barotropic_restart:
ocean_barotropic_end:
maximum_convrhoud:
barotropic_chksum:
psi_compute:
eta_terms_diagnose:
eta_truncate:
eta_check:
tidal_forcing_init:
geoid_forcing_init:
get_tidal_forcing:
ideal_initialize_eta:
REMAP_BT_TO_BU_LOCAL:

PUBLIC DATA

None.

PUBLIC ROUTINES

  1. ocean_barotropic_init

    DESCRIPTION
    Initialize the barotropic module


  2. eta_and_pbot_update

    DESCRIPTION
    Time step the surface height or pbot using a "big" time step. These fields are coincident in time with tracers.

    NOTE: For pbot_t updates, we time step anompb for accuracy, then add rho0grav*ht to get pbot_t.



  3. eta_and_pbot_diagnose

    DESCRIPTION
    Diagnose surface height or pbot depending on the vertical coordinate.

    Note that dzt has been updated to taup1 before this routine is called since we have already called update_tcell_thickness.

    Also, compute geodepth_zt in this routine. It is necessary to do do this step here, since for pressure coordinate models we do not know eta_t(taup1) until this routine...



  4. eta_and_pbot_tendency

    DESCRIPTION
    Compute tendency for surface height or bottom pressure.


  5. update_ocean_barotropic

    DESCRIPTION
    Time step the external mode fields using either a leap-frog scheme or a predictor-corrector scheme. Time average these fields to update the vertically integrated density weighted velocity (urhod,vrhod) and the time averaged surface height eta_t_bar or bottom pressure anompb_bar.

    NOTE: surface pressure gradient and gradient of anomalous bottom pressure are needed for the energy analysis.

    Also, if splitting=false or update_velocity_via_uprime=.false., use these for velocity update in ocean_velocity_mod.

    Include the tidal forcing if present.

    Include geoid perturbation if present.

    Use time averaged eta and pbot to ensure the most stable pressure gradient for use with splitting=false or update_velocity_via_uprime=.false.



  6. ocean_barotropic_forcing

    DESCRIPTION
    Construct the vertically integrated forcing. This forcing is to be held constant over the barotropic timesteps. At the time of calling this routine, accel has the contributions from explicit-time forcing, except for the following:

    1. Coriolis force is updated on the barotropic time steps when integrating the barotropic dynamics. So it should not be included in forcing_bt.

    2. Contributions from smf and bmf are added to forcing_bt to allow for simpler handling of vertical friction implicitly in time.

    3. The accel array is already thickness and density weighted, so a vertical density weighted integral is here just a vertical sum.



  7. ocean_mass_forcing

    DESCRIPTION
    Construct the vertically integrated mass source for evolution of the free surface and/or bottom pressure.

    Also construct the time tendency for the atmospheric pressure.



  8. leap_frog_barotropic_depth

    DESCRIPTION
    Integrate barotropic dynamics for "nts" timesteps using leapfrog. Assume a depth-like vertical coordinate, so solve for surface height.


  9. pred_corr_barotropic_depth

    DESCRIPTION
    Integrate barotropic dynamics for "nts" timesteps using predictor-corrector. Assume depth-like vertical coordinate so solve for surface height.

    This scheme is more stable than the leap_frog since it can run with longer time steps to resolve external mode gravity waves. It also provides some extra smoothing when pred_corr_gamma > 0 and so the options smooth_eta_t_bt_laplacian and smooth_eta_t_bt_biharmonic may not be needed.

    Note that OBC has not been tested for use with predictor-corrector.



  10. pred_corr_barotropic_press

    DESCRIPTION
    Integrate barotropic dynamics for "nts" timesteps using predictor-corrector. Assume pressure-like vertical coordinate so solve here for the bottom pressure.

    This scheme provides some smoothing of small spatial scales when pred_corr_gamma > 0.

    NOTE: the pressure gradient force is based on gradients of (pbot_t_bt - rho0*grav*ht) rather than gradients of pbot_t_bt. This approach aims to improve accuracy of the pressure force.



  11. eta_smooth_diagnosed

    DESCRIPTION
    Smooth eta_t for case when running with pressure models and wish to have a diagnostic eta field smoothed.


  12. ocean_eta_smooth

    DESCRIPTION
    Compute tendency for smoothing eta and tracer.

    Use either a laplacian or a biharmonic smoothing operator. Recommend against using the biharmonic, since it is not a positive definite operator and so can lead to extrema.


  13. ocean_pbot_smooth

    DESCRIPTION
    Compute tendency for diffusion of (pbot_t-pbot0) in both pbot_t and tracer. Need to consider tracer in order to maintain compability between tracer and mass conservation equations.

    Use either a laplacian or a biharmonic smoother.

    Recommend against using the biharmonic, since it is NOT a positive definite operator and so can lead to extrema.


  14. barotropic_integrals

    DESCRIPTION
    Compute area averaged fresh water and surface height and ocean mass.


  15. barotropic_energy

    DESCRIPTION
    Compute energetics of vertically integrated flow.


  16. read_barotropic

    DESCRIPTION
    Read in external mode fields from restart file.


  17. ocean_barotropic_restart

    DESCRIPTION
    Write out restart files registered through register_restart_file Call to reset_field_pointer only needed for fields with a time index.



  18. ocean_barotropic_end

    DESCRIPTION
    Write out external mode fields to restart file.


  19. maximum_convrhoud

    DESCRIPTION
    Compute maximum convergence(rho_ud,rho_vd).


  20. barotropic_chksum

    DESCRIPTION
    Compute checksum for external mode fields.


  21. psi_compute

    DESCRIPTION
    Compute quasi-barotropic streamfunctions for diagnostic purposes. When no fresh water and steady state, these two streamfunctions will be equal, and they will be equal to the rigid lid barotropic streamfunction in the Boussinesq case.

    Original algorithm: Stephen.Griffies@noaa.gov Modifications for parallel efficiency: Giang.Nong@noaa.gov

    13MAR2007: Change units to 10^9 kg/s, which is a "mass Sv" This is the natural unit of transport for a mass-based vertical coordinate model.

    Updated Dec2009 to be compatible with tx_trans and ty_trans calculation.



  22. eta_terms_diagnose

    DESCRIPTION
    Diagnose various contributions to the sea level.

    WARNING: The steric diagnostics from this subroutine are confusing when evaluated in a Boussinesq model. The reason is that volume conserving Boussinesq models have spurious mass sources, which corrupt the bottom pressure signal. One needs to apply corrections to make sense of the Boussinesq models for purposes of studying mass budgets, including the local contribution to steric effects.

    A/ contributions from dynamics, eustatic, and steric:

    eta_nonbouss = (eta_dynamic + eta_water + eta_source) + eta_steric = eta_nonsteric + eta_steric

    The time stepping diagnosed in this subroutine can lead to individual components to etanb that are quite huge. The resulting sum, however, should be quite close to eta_t. In particular, locations of fresh water input can create eta_water that grows unboundedely, with a compenstating eta_dynamic that is negative, accounting for the dynamical adjustment accuring in the presence of water introduced to the ocean.

    For PRESSURE_BASED vertical coordinates, eta_smooth_tend has already been computed in subroutine eta_smooth_diagnosed. We do not add this contribution to eta_nonbouss, since this piece is not part of the tendencies affecting bottom pressure. It is only added for cosmetic reasons. It is for this reason that eta_smooth is NOT included in the restart file.

    For calculation of the steric contribution, a single time step scheme is assumed, which is the recommended time stepping in MOM4p1.

    For DEPTH_BASED models, the smoothing of eta is included in Ext_mode%source, so eta_smooth_tend is zero for depth-based models.

    For PRESSURE_BASED vertical coordinates, eta_nonbouss as computed in this routine is very close to the prognostic eta_t. Differences arise from any possible smoothing applied to the diagnosed eta_t.

    B/ contributions from boundary fluxes, with residual due to SGS fluxes and nonlinear equation of state.



  23. eta_truncate

    DESCRIPTION
    Truncate eta_t to keep

    dzt(1) + eta_t >= frac_crit_cell_height*dzt(1)

    and

    eta_t <= eta_max

    May be needed when run GEOPOTENTIAL models.



  24. eta_check

    DESCRIPTION
    Perform diagnostic check on top cell thickness. Useful when when use GEOPOTENTIAL vertical coordinate.



  25. tidal_forcing_init

    DESCRIPTION
    Initialize fields needed for lunar and solar tidal forcing.


  26. geoid_forcing_init

    DESCRIPTION
    Initialize fields needed for modifying the geoid, relative to the standard geoid.


  27. get_tidal_forcing

    DESCRIPTION
    Compute equilibrium tidal forcing.


  28. ideal_initialize_eta

    DESCRIPTION
    Idealized initial condition for eta.


  29. REMAP_BT_TO_BU_LOCAL

    DESCRIPTION
    Local version of the operator, needed here for initialization when read in eta information from an initialization file. Since barotropic is initialized prior to operators, we need to have this operator here locally.


NAMELIST

&ocean_barotropic_nml

write_a_restart
Set true to write a restart. False setting only for rare cases where wish to benchmark model without measuring the cost of writing restarts and associated chksums. Default is write_a_restart=.true.
[logical]
zero_tendency
If true, will not integrate the barotropic fields.
[logical]
zero_forcing_bt
Will set to zero all of the terms forcing the barotropic velocity.
[logical]
zero_nonlinear_forcing_bt
Will set to zero the nonlinear forcing terms, leaving only the smf and bmf terms to force the barotropic velocity.
[logical]
zero_eta_ic
To initialize eta_t to zero.
[logical]
zero_eta_t
To maintain eta_t at zero, but to allow other fields to evolve For debugging. Default zero_eta_t=.false.
[logical]
zero_eta_u
To maintain eta_u at zero, but to allow other fields to evolve For debugging. Default zero_eta_u=.false.
[logical]
zero_eta_tendency
To maintain deta_dt at zero. For debugging. Default zero_eta_t=.false.
[logical]
ideal_initial_eta
To initialize eta_t to an ideal profile. This overrides all other initialization that may have occurred. Default=.false.
[logical]
ideal_initial_eta_amplitude
Amplitude for initializing eta with an ideal profile. Default ideal_initial_eta_amplitude = 5.0
[real, units: metre]
ideal_initial_eta_xwidth
Width in x-direction for sine-wave profile. Default xwidth=100e3
[real, units: metre]
ideal_initial_eta_ywidth
Width in y-direction for sine-wave profile. Default ywidth=100e3
[real, units: metre]
barotropic_time_stepping_mom4p0
Use the general approach from mom4p0, in which the eta_t and pbot_t fields are updated with a big time step. This approach can be used with either barotropic predictor-corrector or barotropic leap-frog. Default barotropic_time_stepping_mom4p0=.false.
[logical]
barotropic_time_stepping_mom4p1
Use the alternative approach in which we assume the barotropic scheme is a predictor-corrector. In this way, the eta_t and pbot_t fields are updated with a time average. This approach is only available when using barotropic_pred_corr=.true. Default barotropic_time_stepping_mom4p1=.false.
[logical]
barotropic_leap_frog
Use leap-frog scheme for barotropic time stepping. Not the recommended method, since it requires smaller time steps. It is maintained for legacy purposes. Default barotropic_leap_frog=.false.
[logical]
robert_asselin_bt
Robert time filter for use with leap-frog scheme for barotropic.
[real]
barotropic_pred_corr
Use preditor-corrector for barotropic time stepping. This is the recommended method. Default barotropic_pred_corr=.true.
[logical]
pred_corr_gamma
Dimensionless dissipation parameter for the preditor-corrector scheme. Setting pred_corr_gamma=0.0 reduces the scheme to a forward-backward, but it has been found to be unstable. So pred_corr_gamma > 0.0 is recommended. Note that pred_corr_gamma > 0.25 may be over-dissipated and so may go unstable.
[real, units: dimensionless]
smooth_eta_t_bt_laplacian
For spatially smoothing the eta_t field at each barotropic time step using a Laplacian operator. May not be necessary when running with barotropic_pred_corr=.true. and pred_corr_gamma > 0.0, since predictor-corrector has dissipation from pred_corr_gamma > 0.0. Applicable just for DEPTH_BASED vertical coordinates.
[logical]
smooth_eta_t_bt_biharmonic
For spatially smoothing the eta_t field at each barotropic time step using a biharmonic operator. May not be necessary when running with barotropic_pred_corr=.true. and pred_corr_gamma > 0.0, since predictor-corrector has dissipation from pred_corr_gamma > 0.0. Applicable just for DEPTH_BASED vertical coordinates. WARNING: This operator is NOT positive definite, and so can produce spurious extrema. It is not recommended just for this reason.
[logical]
smooth_eta_t_laplacian
For spatially smoothing the eta_t field on the big time step by using a laplacian operator. For compatibility and global conservation, must also introduce a mixing to the thickness weighted tracer concentration in the k=1 cell. Applicable just for DEPTH_BASED vertical coordinates.
[logical]
smooth_eta_t_biharmonic
For spatially smoothing the eta_t field on the big time step by using a biharmonic operator. For compatibility and global conservation, must also introduce a mixing to the thickness weighted tracer concentration in the k=1 cell. Applicable just for DEPTH_BASED vertical coordinates. WARNING: This operator is NOT positive definite, and so can produce spurious extrema. It is not recommended just for this reason.
[logical]
eta_offset
Uniform offset for use in determining the filter acting on tracer when smoothing the surface height. Default eta_offset=1e-12.
[real, units: metre]
smooth_eta_diag_laplacian
For spatially smoothing the diagnosed eta_t field using a laplacian operator. Default smooth_eta_diag_laplacian=.true.
[logical]
smooth_eta_diag_biharmonic
For spatially smoothing the diagnosed eta_t field using a biharmonic operator. Default smooth_eta_diag_biharmonic=.false.
[logical]
vel_micom_lap_diag
Velocity scale that is used for computing the MICOM Laplacian mixing coefficient used in the Laplacian smoothing of diagnosed surface height.
[real, units: m/sec]
vel_micom_bih_diag
Velocity scale that is used for computing the MICOM biharmonic mixing coefficient used in the biharmonic smoothing of diagnosed surface height.
[real, units: m/sec]
smooth_anompb_bt_laplacian
For spatially smoothing anomalous pbot_t at each barotropic time step using a Laplacian operator. May not be necessary when running with barotropic_pred_corr=.true. and pred_corr_gamma > 0.0, since predictor-corrector has dissipation from pred_corr_gamma > 0.0. Applicable just for PRESSURE_BASED vertical coordinates.
[logical]
smooth_anompb_bt_biharmonic
For spatially smoothing the anomalous pbot_t field at each barotropic time step using a biharmonic operator. May not be necessary when running with barotropic_pred_corr=.true. and pred_corr_gamma > 0.0, since predictor-corrector has dissipation from pred_corr_gamma > 0.0. Applicable just for PRESSURE_BASED vertical coordinates. WARNING: This operator is NOT positive definite, and so can produce spurious extrema. It is not recommended just for this reason.
[logical]
smooth_pbot_t_laplacian
For spatially smoothing pbot_t-pbot0 on the big time step using a laplacian operator. For compatibility and global conservation, must also introduce a mixing to the thickness weighted tracer concentration in the k=kbot cell. Applicable just for PRESSURE_BASED vertical coordinates.
[logical]
smooth_pbot_t_biharmonic
For spatially smoothing pbot_t-pbot0 on the big time step by using a biharmonic operator. For compatibility and global conservation, must also introduce a mixing to the thickness weighted tracer concentration in the k=kbot cell. Applicable just for PRESSURE_BASED vertical coordinates. WARNING: This operator is NOT positive definite, and so can produce spurious extrema. It is not recommended just for this reason.
[logical]
pbot_offset
Uniform offset for use in determining the filter acting on tracer when smoothing the bottom pressure anomaly. Default pbot_offset=1e-12.
[real, units: Pa]
vel_micom_lap
Velocity scale that is used for computing the MICOM Laplacian mixing coefficient used in the Laplacian smoothing of surface height or anomalous bottom pressure.
[real, units: m/sec]
vel_micom_bih
Velocity scale that is used for computing the MICOM biharmonic mixing coefficient used in the biharmonic smoothing of surface height or anomalous bottom pressure.
[real, units: m/sec]
udrho_bt_lap
For non-geopotential vertical coordinates, the vertically integrated horizontal momentum can be noisy. It is therefore useful to add a smoothing operator. Here, we apply the laplacian friction as coded in the friction module using the vertically averaged isotropic viscosity as well as a background. Do so on each barotropic time step. Default udrho_bt_lap=.false.
[logical]
udrho_bt_bih
For non-geopotential vertical coordinates, the vertically integrated horizontal momentum can be noisy. It is therefore useful to add a smoothing operator. Here, we apply the biharmonic friction as coded in the friction module using the vertically averaged isotropic viscosity as well as a background. Do so on each barotropic time step. Default udrho_bt_bih=.false.
[logical]
udrho_lap
For non-geopotential vertical coordinates, the vertically integrated horizontal momentum can be noisy. It is therefore useful to add a smoothing operator. Here, we apply the laplacian friction as coded in the friction module using the vertically averaged isotropic viscosity as well as a background. Do so just on the baroclinic time step. Default udrho_lap=.false.
[logical]
udrho_bih
For non-geopotential vertical coordinates, the vertically integrated horizontal momentum can be noisy. It is therefore useful to add a smoothing operator. Here, we apply the biharmonic friction as coded in the friction module using the vertically averaged isotropic viscosity as well as a background. Do so just on the baroclinic time step. Default udrho_bih=.false.
[logical]
udrho_lap_vel_micom
Velocity scale that is used for computing the MICOM Laplacian mixing coefficient used in the Laplacian smoothing of udrho. Default udrho_lap_vel_micom=.05
[real, units: m/sec]
udrho_bih_vel_micom
Velocity scale that is used for computing the MICOM biharmonic mixing coefficient used in the biharmonic smoothing of udrho. Default udrho_bih_vel_micom=.01
[real, units: m/sec]
tidal_forcing_m2
Forces from lunar M2 tidal constituent.
[logical]
tidal_forcing_8
Forces from 8 lunar and solar tidal constituents.
[logical]
tidal_forcing_ideal
For ideal tidal forcing, which has a bump configuration.
[logical]
geoid_forcing
For modifying the geoid, implemented as a time independent tidal forcing. Need to read in a file to obtain the offset geoid profile. Default geoid_forcing=.false.
[logical]
barotropic_bmf
To apply bottom drag over each barotropic time step. Note that enhanced drag from unresolved tides is not facilitated with this approach. Default barotropic_bmf=.false.
[logical]
barotropic_bmf_cdbot
Dimensionless bottom drag coefficient for applying the bottom drag on the barotropic time step. Default barotropic_bmf_cdbot=1e-3.
[real, units: dimensionless]
truncate_eta
To truncate the surface height deviation so to ensure positive thickness within the top cell. This method will not conserve volume or tracer. It is coded for cases when conservation is not critical but wish to run GEOPOTENTIAL models w/ large free surface height deviations, such as when running with tides and very fine vertical resolution.
[logical]
verbose_truncate
For verbose printout on truncate_eta
[logical]
frac_crit_cell_height
When use GEOPOTENTIAL vertical coordinate, the top model tracer grid cell has thickness dzt(i,j,1) = dzt(1) + eta_t(i,j). 0 < frac_crit_cell_height <= 1 sets the fraction of dzt(1) that is allowed prior to bringing the model down due to overly small dzt(i,j,1).
[real, units: dimensionless]
eta_max
The maximum positive eta_t allowed when truncate_eta is true.
[real, units: meter]
debug_this_module
Print out lots of diagnostics of use for debugging.
[logical]
verbose_init
For brief or full printout on initialization
[logical]
diag_step
Frequency for output of ascii barotropic diagnostics.
[integer]

DATA SETS

None.

ERROR MESSAGES

None.

REFERENCES

  1. S.M. Griffies, R.C. Pacanowski, R.M. Schmidt, and V. Balaji Tracer Conservation with an Explicit Free Surface Method for Z-coordinate Ocean Models Monthly Weather Review (2001) vol 129 pages 1081--1098
  2. S.M. Griffies Fundamentals of Ocean Climate Models Princeton University Press (2004)
  3. S.M. Griffies, M.J. Harrison, R.C. Pacanowski, and A. Rosati A Technical Guide to MOM4 (2004)
  4. S.M. Griffies: Elements of MOM4p1 (2006)

COMPILER SPECIFICS

None.

PRECOMPILER OPTIONS

None.

LOADER OPTIONS

None.

TEST PROGRAM

None.

KNOWN BUGS

None.

NOTES

None.

FUTURE PLANS

None.

top