PUBLIC INTERFACE ~ PUBLIC ROUTINES ~ NAMELIST

Module ocean_sbc_mod

Contact:  S. M. Griffies
Reviewers:  M.J. Harrison ,  A. Rosati ,  V. Balaji
Change History: WebCVS Log

OVERVIEW

Set up the surface boundary conditions for MOM.

This module sets up the surface boundary conditions for MOM. Also fill Ocean_sfc derived-type used to pass information to other component models. Also write diagnostics related to surface boundary forcing. The surface temperature should be the surface insitu temperature, which is the same as the surface potential temperature. When the model prognostic temperature variable is conservative temperature, then the surface potential temperature is carried in T_diag(index_diag_temp). The resulting heat flux is potential enthalpy, which is the correct field to be forcing the T_prog(index_temp) field when the prognostic temperature field is the conservative temperature. We assume the winds passed to the ocean are on the B-grid velocity point. Likewise, we pass the currents back to the coupler on the B-grid point. Code will need to be modified if using another assumption.

OTHER MODULES USED

           constants_mod
        diag_manager_mod
                 fms_mod
              fms_io_mod
         mpp_domains_mod
                 mpp_mod
time_interp_external_mod
        time_manager_mod
       ocean_domains_mod
    ocean_parameters_mod
   ocean_riverspread_mod
   ocean_tracer_util_mod
           ocean_tpm_mod
         ocean_types_mod
     ocean_workspace_mod

PUBLIC INTERFACE

ocean_sbc_init:
ocean_sbc_diag_init:
initialize_ocean_sfc:
sum_ocean_sfc:
zero_ocean_sfc:
avg_ocean_sfc:
ocean_sfc_restart:
ocean_sfc_end:
get_ocean_sbc:
flux_adjust:
ocean_sbc_diag:
:
:

PUBLIC ROUTINES

  1. ocean_sbc_init

    DESCRIPTION
    Initialize the ocean sbc module.


  2. ocean_sbc_diag_init

    DESCRIPTION
    Initialize the ocean sbc diagnostics. Send some static diagnostics to diagnostic manager.


  3. initialize_ocean_sfc

    DESCRIPTION
    Initialize the ocean surface type, which passes information between ocean and other component models. Note that ocean model sst passed to the atmosphere must be the surface potential temperature (which is equated to surface in situ temperature). If the ocean prognostic temperature variable is conservative temperature, then the sst is carried in T_diag(index_diag_temp). If the prognostic temperature is potential temperature, then the sst is carried in T_prog(index_temp). Note that we assume the winds passed to the ocean are on the B-grid velocity point. Likewise, we pass the currents back to the coupler on the B-grid point. Code will need to be modified if using another coupler assumption. Ocean_sfc%t_surf = time averaged sst (Kelvin) passed to atmosphere/ice model Ocean_sfc%s_surf = time averaged sss (psu) passed to atmosphere/ice models Ocean_sfc%u_surf = time averaged u-current (m/sec) passed to atmosphere/ice models Ocean_sfc%v_surf = time averaged v-current (m/sec) passed to atmosphere/ice models Ocean_sfc%sea_lev = time averaged ocean free surface height (m) plus patm/(grav*rho0) Ocean_sfc%frazil = time accumulated frazil (J/m^2) passed to ice model. time averaging not performed, since ice model needs the frazil accumulated over the ocean time steps. Note that Ocean_sfc%frazil is accumulated, whereas T_diag%frazil (saved in diagnostic tracer restart file) is instantaneous.


  4. sum_ocean_sfc

    DESCRIPTION
    Accumulate the ocean_sfc derived type over the course of the ocean component sub-cycling used when coupling to other models. Note that ocean model sst passed to the atmosphere must be the surface potential temperature (which is equated to surface in situ temperature). If the ocean prognostic temperature variable is conservative temperature, then the sst is carried in T_diag(index_diag_temp). If the prognostic temperature is potential temperature, then the sst is carried in T_prog(index_temp). Note that this routine is called after eta_and_pbot_diagnose, so Thickness%eta is eta_t(taup1).


  5. zero_ocean_sfc

    DESCRIPTION
    Zero the elements of the Ocean_sfc derived type.


  6. avg_ocean_sfc

    DESCRIPTION
    Compute average of ocean surface quantities. This is for coupling, where pass time averaged information from ocean to other component models. Note that Ocean_sfc%frazil is NOT time averaged. Rather, it is accumulated from T_diag(index_frazil)%field in subroutine sum_ocean_sfc. Doing so is necessary for heat conservation between ocean and sea ice systems. Since it is not time averaged, frazil is not part of this averaging subroutine. Note that ocean model SST passed to the atmosphere is the surface potential temperature (which is equal to surface in situ temperature). If the ocean prognostic temperature variable is conservative temperature, then the sst is carried in T_diag(index_diag_temp). If the prognostic temperature is potential temperature, then the sst is carried in T_prog(index_temp). Note that if one removes the averaging, then we take only the latest values of the surface fields. This approach has been found useful to stabilize the "concurrent" coupling approach. Note that this routine is called after eta_and_pbot_diagnose, so Thickness%eta is eta_t(taup1).


  7. ocean_sfc_restart

    DESCRIPTION
    Write out restart files registered through register_restart_file


  8. ocean_sfc_end

    DESCRIPTION
    Save information from Ocean_sfc to restarts. Note that it is important in general to distinguish the time accumulated quantity Ocean_sfc%frazil, saved here, from the instantaneous quantity T_diag%frazil, which is saved in the diagnostic tracer restart file.


  9. get_ocean_sbc

    DESCRIPTION
    Subroutine to get the surface fluxes passed into the ocean from other component models. **momentum fluxes from wind stress and momentum of pme and rivers **stokes drift from surface wave model **water fluxes and temp/salinity in water fluxes **salt fluxes; real or virtual **heat fluxes **applied surface pressure


  10. flux_adjust

    DESCRIPTION
    Subroutine to compute the surface fluxes derived from a restoring condition and/or correction from an input file. We use a convention whereby a positive flux enters the ocean: (+) down convention. When restoring salinity, one may choose to convert this flux to an implied water flux, or keep it a salt flux. Converting to a water flux will alter the sea level, and so alter the concentration of other tracers. The default is to keep it as a salt flux.


  11. ocean_sbc_diag

    DESCRIPTION
    Compute and send diagnostics from get_ocean_sbc.


  12. DESCRIPTION
    TEOS-10 expression for latent heat of fusion at the sea surface (p=0dbar) The following is from the from the matlab routine due to McDougall and Barker with respect to the full pressure dependent formulation. Note that the computed latent heat of fusion from this function has errors that range between -0.4 and 0.3 J kg^-1, when compared with the latent heats of melting derived from the Gibbs functions of ice and of seawater (using the SIA code of TEOS-10). However, the underlying data to the Gibbs function contains uncertainities of 200 J kg^-1 (IOC et al., 2010). The reference for this routine is IOC, SCOR and IAPSO, 2010: The international thermodynamic equation of seawater - 2010: Calculation and use of thermodynamic properties. Intergovernmental Oceanographic Commission, Manuals and Guides No. 56, UNESCO (English), 196 pp. Available from http://www.TEOS-10.org See section 3.34 of the TEOS-10 Manual.


  13. DESCRIPTION
    TEOS-10 expression for latent heat of vaporization at the sea surface (p=0dbar). The following is from the From the original matlab routine due to Barker, McDougall and Feistel Calculates latent heat, or enthalpy, of evaporation at p = 0 (the surface). It is defined as a function of Absolute Salinity, SA, and Conservative Temperature, CT, and is valid in the ranges 0 < SA < 42 g/kg and 0 < CT < 40 deg C. The errors range between -0.4 and 0.6 J/kg IOC, SCOR and IAPSO, 2010: The international thermodynamic equation of seawater - 2010: Calculation and use of thermodynamic properties. Intergovernmental Oceanographic Commission, Manuals and Guides No. 56, UNESCO (English), 196 pp. Available from http://www.TEOS-10.org See section 3.39 of the TEOS-10 Manual.


NAMELIST

&ocean_sbc_nml

use_waterflux
Set to true when wish to use real fresh water flux as opposed to virtual salt fluxes. This is the recommended method. The alternative virtual tracer flux method (use_waterflux=.false.) is not routinely used at GFDL, so it may suffer from poor testing. Default use_waterflux=.true.
[logical]
waterflux_tavg
Set to true when aiming to suppress the leap-frog computational mode by setting pme and river equal to a time averaged value over the present and previous time step. This method requires an extra field in the restart file. This method is not needed when using the TWO_LEVEL time tendency. It remains for those who wish to use the leap-frog THREE_LEVEL time stepping scheme. Note that it does not lead to simple checks of conservation across model components, since there is a time averaging performed for the water flux added to the ocean model. It is generally NOT recommended. Default waterflux_tavg=.false.
[logical]
use_ideal_runoff
To add an idealized liquid runoff read from a file. This runoff is assumed to enter the ocean with the same temperature as SST, and to be liquid. It is an additional runoff, so that any other runoff remains unaltered. The runoff coming from idealized runoff is NOT subject to the global normalization realized from zero_net_water_coupler=.true. Default use_ideal_runoff=.false.
[logical]
use_ideal_calving
To add an idealized solid runoff or calving read from a file. This calving runoff is assumed to require melting, so it extracts latent heat of fusion from the liquid ocean The runoff coming from idealized cavling is NOT subject to the global normalization realized from zero_net_water_coupler=.true. Default use_ideal_calving=.false.
[logical]
use_waterflux_override_calving
Set to true will allow for model to incorporate the latent heating from a calving field that comes in through coupled model instantaneous interactions, but later will over-ride the mass flux from calving with a dataset that is read in from a climatology or observations. The idea is to only modify the mass contribution from calving through the over-ride, and leave the latent heat contribution untouched. Default use_waterflux_override_calving=.false.
[logical]
use_waterflux_override_fprec
Set to true will allow for model to incorporate the latent heating from a fprec field that comes in through coupled model instantaneous interactions, but later will over-ride the mass flux from fprec with a dataset that is read in from a climatology or observations. The idea is to only modify the mass contribution from fprec through the over-ride, and leave the latent heat contribution untouched. Default use_waterflux_override_fprec=.false.
[logical]
use_waterflux_override_evap
Set to true will allow for model to incorporate the latent heating from an evap field that comes in through coupled model instantaneous interactions, but later will over-ride the mass flux from evap with a dataset that is read in from a climatology or observations. The idea is to only modify the mass contribution from evap through the over-ride, and leave the latent heat contribution untouched. Default use_waterflux_override_evap=.false.
[logical]
temp_restore_tscale
Time scale in days for restoring temperature within the top model grid cell.
[real, units: day]
salt_restore_tscale
Time scale in days for restoring salinity within the top model grid cell.
[real, units: day]
eta_restore_tscale
Time scale in days for restoring surface height to produce a modification to surface water flux. This option is only available when run with use_waterflux=.true.
[real, units: day]
use_constant_sst_for_restore
To over-ride the sfc_restore.nc value for temp restoring. use_constant_sst_for_restore=.false.
[logical]
constant_sst_for_restore
The SST value used if use_constant_sst_for_restore=.true. Default constant_sst_for_restore=12.0
[real, units: degC]
salt_restore_as_salt_flux
When running a use_waterflux=.true. model, we may choose to add the salinity from a restoring condition as a salt flux or convert to a fresh water flux. The addition of salt does not alter the sea level nor does it alter the concentration of other tracers, whereas converting to an implied water flux will alter sea level and other concentrations. So we generally recommend the default salt_restore_as_salt_flux=.true.
[logical]
use_constant_sss_for_restore
To over-ride the sfc_restore.nc value for salinity restoring. use_constant_sss_for_restore=.false.
[logical]
constant_sss_for_restore
The SSS value used if use_constant_sss_for_restore=.true. Default constant_sss_for_restore=35.0
[real, units: psu]
max_delta_salinity_restore
When computing the restoring flux for salinity, we can define a maximum absolute value for the difference between salinity(k=1) and the restoring salinity from a dataset. This approach is useful especially in NAtl western boundary, where poor Gulf Stream separation can lead to large salinity biases. If restore too much the salinity field, we can spuriously transport large amounts of fresh water to the subpoloar gyre, thus impacting the overturning circulation too much. If max_delta_salinity_restore < 0.0, then will NOT provide a max to the delta salinity; will instead compute an unbounded restoring flux. Default max_delta_salinity_restore=-0.50.
[real, units: ppt]
read_restore_mask
For reading in a mask that selects regions of the domain that are restored (mask=1) or not restored (mask=0). Default read_restore_mask=.false., whereby restore_mask is set to tmask(k=1).
[logical]
restore_mask_gfdl
For modifying the restore mask based on reading in the GFDL regional mask. Default restore_mask_gfdl=.false.
[logical]
salinity_ref
Reference salinity used for converting fresh water flux to salt flux.
[real, units: psu]
salt_restore_under_ice
Logical indicating whether to restore salinity under sea ice or not. When .false. then will not restore salinity in regions where we use a "frazil" condition as a proxy for where sea-ice is present. Do not use sea ice extent from a sea ice model since we generally do not pass information regarding ice extent between the sea ice model and the ocean model.
[logical]
zero_net_salt_restore
Logical indicating whether to remove the area mean of the salinity restore flux so there is a net zero input of salt to the ocean associated with restoring.
[logical]
zero_net_salt_correction
Logical indicating whether to remove the area mean of the salinity correction flux so there is a net zero input of salt to the ocean associated with salt correction.
[logical]
zero_net_water_restore
Logical indicating whether to remove the area mean of the water restore flux so there is a net zero input of water to the ocean associated with restoring.
[logical]
zero_net_water_correction
Logical indicating whether to remove the area mean of the water correction flux so there is a net zero input of water to the ocean associated with water correction.
[logical]
zero_net_water_coupler
Logical indicating whether to remove the area mean of the water passed through the coupler so there is a net zero input of fresh water to the ocean associated with p-e+r. Do so by removing area mean from pme--keep river values unchanged. Note that a choice must be made whether to remove the area mean from rivers or pme. We choose pme since it is more evenly distributed than rivers. Also note that we DO NOT include the ice melt in this normalization. The reason is that we only wish to ensure the ocean+ice system has a zero net water. When melt or form sea ice, this only transfers water between liquid ocean and solid sea ice, and no normalization is appropriate for this case. It is only the water exchanged with the land and atmosphere that is normalized.
[logical]
zero_net_water_couple_restore
This logical keeps the total water forcing on the ocean+ice system to a global mean of zero at each time step. We DO NOT include the ice melt in this normalization. Setting zero_net_water_couple_restore to true may be appropriate when running an ice-ocean model using a bulk formulae to compute evaporation (e.g., CORE) and when only providing a weak (or zero) salinity restoring. It is not appropriate when running a coupled ocean-atmosphere model, where the moisture budget should be conserved without an artificial removal of the global mean.
[logical]
land_model_heat_fluxes
For the case where land model passes through the coupler the heat flux associated with the liquid runoff and calving land ice fields. This heat flux is computed relative to 0C, and takes the form heat flux = mass flux of water * temp of water * heat capacity, where the water can be either liquid or solid. For many coupled models, the water temperature is assumed to be that of the SST. But more complete land models now carry the heat of its water relative to 0C, in which case the ocean model does not need to assume anything about the heat content of the land water. Default land_model_heat_fluxes=.false.
[logical]
debug_water_fluxes
Logical for debugging water fluxes. Must be true for any of the options zero_water_fluxes, zero_calving_fluxes, zero_pme_fluxes or zero_runoff_fluxes to be enabled. Default debug_water_fluxes=.false.
[logical]
zero_water_fluxes
Logical for debugging to zero the pme, river, and pme_taum1 into ocean, over-riding any input from Ice_ocean_boundary. Default zero_water_fluxes=.false.
[logical]
zero_calving_fluxes
Logical for debugging to zero the calving flux passed into the ocean. Default zero_calving_fluxes=.false.
[logical]
zero_pme_fluxes
Logical for debugging to zero the pme flux passed into the ocean. Default zero_pme_fluxes=.false.
[logical]
zero_runoff_fluxes
Logical for debugging to zero the runoff flux passed into the ocean. Default zero_runoff_fluxes=.false.
[logical]
zero_river_fluxes
Logical for debugging to zero the river (calving+runoff) flux passed into the ocean. Default zero_river_fluxes=.false.
[logical]
convert_river_to_pme
Logical for debugging. Here we add the river water input (calving+runoff) to pme, then set river=calving=runoff=0.0. Default convert_river_to_pme=.false.
[logical]
sbc_heat_fluxes_const
Logical for setting the surface heat flux from the coupler to a global constant. Default is sbc_heat_fluxes_const=.false.
[logical]
sbc_heat_fluxes_const_seasonal
Logical for setting the surface heat flux from the coupler to a global constant, and giving it a seasonally varying amplitude. Default is sbc_heat_fluxes_const_seasonal=.false.
[logical]
sbc_heat_fluxes_const_value
Value for the constant heat flux when using sbc_heat_fluxes_const=.true. Default sbc_heat_fluxes_const_value=0.0.
[real, units: W/m2]
zero_heat_fluxes
Logical for debugging to set all heat fluxes into the ocean to zero, over-riding any input from Ice_ocean_boundary. Default is .false.
[logical]
zero_surface_stress
Logical for debugging to zero all surface stress applied to the ocean, over-riding any input from Ice_ocean_boundary. Default is .false.
[logical]
rotate_winds
Set to true when need to rotate the winds onto the ocean model grid. This is needed for cases where the winds are on a spherical grid and the ocean model uses tripolar=.true. If generate the wind data on the ocean model grid, then do not need to rotate, since the rotation has already been done.
[logical]
max_ice_thickness
When coupling MOM to an ice model, the sea ice thickness may need to be restricted to prevent vanishing top-level in MOM. Set max_ice_thickness (meters) < dzt(k=1) to restrict. This truncation avoids the numerical problem but we loose mass conservation in the coupled sea ice and ocean system. We also alter the pressure felt on the ocean as applied by the sea ice. Different vertical coordinates are needed to do the problem more realistically. Note that the problem of vanishing top layer is removed when use either ZSTAR or PSTAR as vertical coordinate.
[real, units: m]
ice_salt_concentration
The salt concentration of sea ice. This is taken as a bulk value, and should be the same as that used by the ice model. Default is ice_salt_concentration=0.005, as that is the value used in the GFDL coupled climate model.
[real, units: kg salt / kg ice]
runoff_salinity
The salinity of river runoff water. Default is runoff_salinity=0.0.
[real, units: g salt / kg runoff water (ppt)]
runoff_temp_min
The minimum temperature that river runoff into the ocean is assigned. Default runoff_temp_min=0.0.
[real, units: DegC]
runoffspread
Set to true if wish to use the spread_river_horz algorithm to spread the river runoff flux horizontally over an area into the ocean wider than set by the coupler. This option requires the setup of a table for determining the points over which we spread. Default runoffspread=.false.
[logical]
calvingspread
Set to true if wish to use the spread_river_horz algorithm to spread the calving flux horizontally over an area into the ocean wider than set by the coupler. This option requires the setup of a table for determining the points over which we spread. Default calvingspread=.false.
[logical]
avg_sfc_velocity
If set to true, the u and v fields passed up to the sea ice are averaged over a coupling interval. TRUE by default.
[logical]
avg_sfc_temp_salt_eta
If set to true, the t, s and sea_level fields passed up to the sea ice are averaged over a coupling interval. TRUE by default.
[logical]
use_full_patm_for_sea_level
The option use_full_patm_for_sea_level allows for the passing of the sea level including the full weight of sea ice back to the ice model. This approach maintains the max weight on the liquid ocean according to the nml variable max_ice_thickness. But it does allow the sea ice to know when there is actually more sea ice than that set by max_ice_thickness. This option then provides for a negative feedback on the runaway growth of sea ice, since the full pressure acting to make the ice flow will be correctly felt. This is a new option, and is not fully tested, So the default is use_full_patm_for_sea_level=.false
[logical]
do_flux_correction
For applying surface flux correction to to a tracer or wind stress field. This code is used at GFDL for idealized perturbation experiments, such as when one wishes to artificially enhance the wind stress to test model sensitivity. It is also appropriate for coupled models that may require a modification to the fluxes arrising from a coupled model, via reading in information from a pre-defined data file, Default do_flux_correction=.false.
[logical]
temp_correction_scale
A scale multiplying the flux correction for temperature. Default temp_correction_scale=0.0.
[real, units: dimensionless]
salt_correction_scale
A scale multiplying the flux correction for salinity. Default salt_correction_scale=0.0.
[real, units: dimensionless]
tau_x_correction_scale
A scale multiplying the flux correction for tau_x. Default tau_x_correction_scale=0.0.
[real, units: dimensionless]
tau_y_correction_scale
A scale multiplying the flux correction for tau_y. Default tau_y_correction_scale=0.0.
[real, units: dimensionless]
do_bitwise_exact_sum
Set true to do bitwise exact global sum. When it is false, the global sum will be non-bitwise_exact, but will significantly increase efficiency. The default value is do_bitwise_exact_sum=.true. in order to ensure answers do not change when alter processors. But if wish to enhance the efficiency of coupled ocean-ice models that use one of the global normalization options zero_net_salt_restore =.true. zero_net_salt_correction =.true. zero_net_water_restore =.true. zero_net_water_correction =.true. zero_net_water_coupler =.true. zero_net_water_couple_restore=.true. then one may wish to consider setting do_bitwise_exact_sum=.false.
[logical]
constant_hlf
Treat latent heat of fusion as a constant. Otherwise, use the TEOS-10 approach in which hlf is function of surface salinity. Note, TEOS-10 approach is only valid using Absolute Salinity and conservative temperature as the prognostic fields. Default constant_hlf = .true., which is the case for pre-TEOS-10 methods.
[logical]
constant_hlv
Treat latent heat of vaporization as a constant. Otherwise, use the TEOS-10 approach in which hlf is function of surface salinity. Note, TEOS-10 approach is only valid using Absolute Salinity and conservative temperature as the prognostic fields. Default constant_hlv = .true., which is the case for pre-TEOS-10 methods.
[logical]
read_stokes_drift
This option is to be used when coupling to a surface wave model such as Wavewatch III that provides both the Stokes drift (m/s) velocity at the ocean surface, and a decay scale for projecting the Stokes drift into the interior. Default read_stokes_drift = .false.
[logical]

top