mom_surface_forcing_gfdl module reference¶

Data Types¶

`surface_forcing_cs`	surface_forcing_CS is a structure containing pointers to the forcing fields which may be used to drive MOM. All fluxes are positive downward.
`ice_ocean_boundary_type`	`ice_ocean_boundary_type()` is a structure corresponding to forcing, but with the elements, units, and conventions that exactly conform to the use for MOM6-based coupled models. is a structure corresponding to forcing, but with the elements, units, and conventions that exactly conform to the use for MOM6-based coupled models.

Functions/Subroutines¶

`convert_iob_to_fluxes()`	This subroutine translates the Ice_ocean_boundary_type into a MOM thermodynamic forcing type, including changes of units, sign conventions, and putting the fields into arrays with MOM-standard halos.
`convert_iob_to_forces()`	This subroutine translates the Ice_ocean_boundary_type into a MOM mechanical forcing type, including changes of units, sign conventions, and putting the fields into arrays with MOM-standard halos.
`extract_iob_stresses()`	This subroutine extracts the wind stresses and related fields like ustar from an Ice_ocean_boundary_type into optional argument arrays, including changes of units, sign conventions, and putting the fields into arrays with MOM-standard sized halos.
`apply_flux_adjustments()`	Adds thermodynamic flux adjustments obtained via data_override Component name is ‘OCN’ Available adjustments are:
`apply_force_adjustments()`	Adds mechanical forcing adjustments obtained via data_override Component name is ‘OCN’ Available adjustments are:
`forcing_save_restart()`	Save any restart files associated with the surface forcing.
`surface_forcing_init()`	Initialize the surface forcing, including setting parameters and allocating permanent memory.
`surface_forcing_end()`	Clean up and deallocate any memory associated with this module and its children.
`ice_ocn_bnd_type_chksum()`	Write out a set of messages with checksums of the fields in an ice_ocean_boundary type.
`check_mask_val_consistency()`	Check the values passed by IOB over land are zero.

Detailed Description¶

Type Documentation¶

type mom_surface_forcing_gfdl/surface_forcing_cs¶

surface_forcing_CS is a structure containing pointers to the forcing fields which may be used to drive MOM. All fluxes are positive downward.

Type fields:

% wind_stagger [integer] :: AGRID, BGRID_NE, or CGRID_NE (integer values from MOM_domains) to indicate the staggering of the winds that are being provided in calls to update_ocean_model.
% use_temperature [logical] :: If true, temp and saln used as state variables.
% nonbous [logical] :: If true, this run is fully non-Boussinesq.
% wind_stress_multiplier [real] :: A multiplier applied to incoming wind stress [nondim].
% rho0 [real] :: Boussinesq reference density [R ~> kg m-3].
% area_surf [real] :: Total ocean surface area [L2 ~> m2].
% latent_heat_fusion [real] :: Latent heat of fusion [Q ~> J kg-1].
% latent_heat_vapor [real] :: Latent heat of vaporization [Q ~> J kg-1].
% max_p_surf [real] :: The maximum surface pressure that can be exerted by the atmosphere and floating sea-ice [R L2 T-2 ~> Pa]. This is needed because the FMS coupling structure does not limit the water that can be frozen out of the ocean and the ice-ocean heat fluxes are treated explicitly.
% use_limited_p_ssh [logical] :: If true, return the sea surface height with the correction for the atmospheric (and sea-ice) pressure limited by max_p_surf instead of the full atmospheric pressure. The default is true.
% approx_net_mass_src [logical] :: If true, use the net mass sources from the ice-ocean boundary type without any further adjustments to drive the ocean dynamics. The actual net mass source may differ due to corrections.
% gust_const [real] :: Constant unresolved background gustiness for ustar [R Z2 T-2 ~> Pa].
% read_gust_2d [logical] :: If true, use a 2-dimensional gustiness supplied from an input file.
% bbl_tidal_dis [real(:,:),pointer] :: Tidal energy dissipation in the bottom boundary layer that can act as a.
% gust [real(:,:),pointer] :: A spatially varying unresolved background gustiness that.
% ustar_tidal [real(:,:),pointer] :: Tidal contribution to the bottom friction velocity [Z T-1 ~> m s-1].
% cd_tides [real] :: Drag coefficient that applies to the tides [nondim].
% utide [real] :: Constant tidal velocity to use if read_tideamp is false [Z T-1 ~> m s-1].
% read_tideamp [logical] :: If true, spatially varying tidal amplitude read from a file.
% rigid_sea_ice [logical] :: If true, sea-ice exerts a rigidity that acts to damp surface deflections (especially surface gravity waves). The default is false.
% g_earth [real] :: Gravitational acceleration [L2 Z-1 T-2 ~> m s-2].
% kv_sea_ice [real] :: Viscosity in sea-ice that resists sheared vertical motions [L4 Z-2 T-1 ~> m2 s-1].
% density_sea_ice [real] :: Typical density of sea-ice [R ~> kg m-3]. The value is only used to convert the ice pressure into appropriate units for use with Kv_sea_ice.
% rigid_sea_ice_mass [real] :: A mass per unit area of sea-ice beyond which sea-ice viscosity becomes effective [R Z ~> kg m-2], typically of order 1000 kg m-2.
% allow_flux_adjustments [logical] :: If true, use data_override to obtain flux adjustments.
% restore_salt [logical] :: If true, the coupled MOM driver adds a term to restore surface salinity to a specified value.
% restore_temp [logical] :: If true, the coupled MOM driver adds a term to restore sea surface temperature to a specified value.
% flux_const_salt [real] :: Piston velocity for surface salinity restoring [Z T-1 ~> m s-1].
% flux_const_temp [real] :: Piston velocity for surface temperature restoring [Z T-1 ~> m s-1].
% rho_restore [real] :: The density that is used to convert piston velocities into salt or heat fluxes with salinity or temperature restoring [R ~> kg m-3].
% trestore_spear_ecda [logical] :: If true, modify restoring data wrt local SSS.
% spear_dtf_ds [real] :: The derivative of the freezing temperature with salinity [C S-1 ~> degC ppt-1].
% salt_restore_as_sflux [logical] :: If true, SSS restore as salt flux instead of water flux.
% adjust_net_srestore_to_zero [logical] :: Adjust srestore to zero (for both salt_flux or vprec)
% adjust_net_srestore_by_scaling [logical] :: Adjust srestore w/o moving zero contour.
% adjust_net_fresh_water_to_zero [logical] :: Adjust net surface fresh-water (with restoring) to zero.
% use_net_fw_adjustment_sign_bug [logical] :: Use the wrong sign when adjusting net FW.
% adjust_net_fresh_water_by_scaling [logical] :: Adjust net surface fresh-water w/o moving zero contour.
% mask_srestore_under_ice [logical] :: If true, use an ice mask defined by frazil criteria for salinity restoring.
% ice_salt_concentration [real] :: Salt concentration for sea ice [kg/kg].
% mask_srestore_marginal_seas [logical] :: If true, then mask SSS restoring in marginal seas.
% max_delta_srestore [real] :: Maximum delta salinity used for restoring [S ~> ppt].
% max_delta_trestore [real] :: Maximum delta sst used for restoring [C ~> degC].
% basin_mask [real(:,:),pointer] :: Mask for surface salinity restoring by basin [nondim].
% answer_date [integer] :: The vintage of the order of arithmetic and expressions in the gustiness calculations. Values below 20190101 recover the answers from the end of 2018, while higher values use a simpler expression to calculate gustiness.
% ustar_gustless_bug [logical] :: If true, include a bug in the time-averaging of the gustless wind friction velocity.
% check_no_land_fluxes [logical] :: Return warning if IOB flux over land is non-zero.
% diag [type( diag_ctrl ),pointer] :: Structure to regulate diagnostic output timing.
% inputdir [character (len=200)] :: Directory where NetCDF input files are.
% salt_restore_file [character (len=200)] :: Filename for salt restoring data.
% salt_restore_var_name [character (len=30)] :: Name of surface salinity in salt_restore_file.
% salt_restore_is_practical [logical] :: Specifies that the target salinity is practical and not absolute.
% mask_srestore [logical] :: If true, apply a 2-dimensional mask to the surface salinity restoring fluxes. The masking file should be in inputdir/salt_restore_mask.nc and the field should be named ‘mask’.
% srestore_mask [real(:,:),pointer] :: mask for SSS restoring [nondim]
% temp_restore_file [character (len=200)] :: Filename for sst restoring data.
% temp_restore_var_name [character (len=30)] :: Name of surface temperature in temp_restore_file.
% mask_trestore [logical] :: If true, apply a 2-dimensional mask to the surface temperature restoring fluxes. The masking file should be in inputdir/temp_restore_mask.nc and the field should be named ‘mask’.
% trestore_mask [real(:,:),pointer] :: Mask for SST restoring [nondim].
% srestore_handle [type(external_field)] :: Handle for time-interpolated salt restoration field.
% trestore_handle [type(external_field)] :: Handle for time-interpolated temperature restoration field.
% handles [type( forcing_diags ),public] :: Diagnostics handles.
% restart_csp [type( mom_restart_cs ),pointer] :: A pointer to the restart control structure.
% urf_cs [type( user_revise_forcing_cs ),pointer] :: A control structure for user forcing revisions.

type mom_surface_forcing_gfdl/ice_ocean_boundary_type¶

ice_ocean_boundary_type() is a structure corresponding to forcing, but with the elements, units, and conventions that exactly conform to the use for MOM6-based coupled models. is a structure corresponding to forcing, but with the elements, units, and conventions that exactly conform to the use for MOM6-based coupled models.

Type fields:

% u_flux [real(:,:),pointer] :: i-direction wind stress [Pa]
% v_flux [real(:,:),pointer] :: j-direction wind stress [Pa]
% t_flux [real(:,:),pointer] :: sensible heat flux [W m-2]
% q_flux [real(:,:),pointer] :: specific humidity flux [kg m-2 s-1]
% salt_flux [real(:,:),pointer] :: salt flux [kg m-2 s-1]
% excess_salt [real(:,:),pointer] :: salt left behind by brine rejection [kg m-2 s-1]
% lw_flux [real(:,:),pointer] :: long wave radiation [W m-2]
% sw_flux_vis_dir [real(:,:),pointer] :: direct visible sw radiation [W m-2]
% sw_flux_vis_dif [real(:,:),pointer] :: diffuse visible sw radiation [W m-2]
% sw_flux_nir_dir [real(:,:),pointer] :: direct Near InfraRed sw radiation [W m-2]
% sw_flux_nir_dif [real(:,:),pointer] :: diffuse Near InfraRed sw radiation [W m-2]
% lprec [real(:,:),pointer] :: mass flux of liquid precip [kg m-2 s-1]
% fprec [real(:,:),pointer] :: mass flux of frozen precip [kg m-2 s-1]
% runoff [real(:,:),pointer] :: mass flux of liquid runoff [kg m-2 s-1]
% calving [real(:,:),pointer] :: mass flux of frozen runoff [kg m-2 s-1]
% stress_mag [real(:,:),pointer] :: The time-mean magnitude of the stress on the ocean [Pa].
% ustar_berg [real(:,:),pointer] :: frictional velocity beneath icebergs [m s-1]
% area_berg [real(:,:),pointer] :: fractional area covered by icebergs [m2 m-2]
% mass_berg [real(:,:),pointer] :: mass of icebergs per unit ocean area [kg m-2]
% runoff_hflx [real(:,:),pointer] :: heat content of liquid runoff [W m-2]
% calving_hflx [real(:,:),pointer] :: heat content of frozen runoff [W m-2]
% p [real(:,:),pointer] :: pressure of overlying ice and atmosphere on ocean surface [Pa]
% mi [real(:,:),pointer] :: mass of ice per unit ocean area [kg m-2]
% ice_rigidity [real(:,:),pointer] :: rigidity of the sea ice, sea-ice and ice-shelves, expressed as a coefficient for divergence damping, as determined outside of the ocean model [m3 s-1]
% shelf_sfc_mass_flux [real(:,:),pointer] :: mass flux to surface of ice sheet [kg m-2 s-1]
% xtype [integer] :: The type of the exchange - REGRID, REDIST or DIRECT.
% fluxes [type(coupler_2d_bc_type)] :: A structure that may contain an array of named fields used for passive tracer fluxes.
% wind_stagger [integer] :: A flag indicating the spatial discretization of wind stresses. This flag may be set by the flux-exchange code, based on what the sea-ice model is providing. Otherwise, the value from the surface_forcing_CS is used.

Function/Subroutine Documentation¶

subroutine mom_surface_forcing_gfdl/convert_iob_to_fluxes(IOB, fluxes, index_bounds, Time, valid_time, G, US, CS, sfc_state)¶

This subroutine translates the Ice_ocean_boundary_type into a MOM thermodynamic forcing type, including changes of units, sign conventions, and putting the fields into arrays with MOM-standard halos.

Parameters:

iob :: [in] An ice-ocean boundary type with fluxes to drive
fluxes :: [inout] A structure containing pointers to all possible mass, heat or salt flux forcing fields. Unused fields have NULL ptrs.
index_bounds :: [in] The i- and j- size of the arrays in IOB.
time :: [in] The time of the fluxes, used for interpolating the salinity to the right time, when it is being restored.
valid_time :: [in] The amount of time over which these fluxes should be applied [T ~> s].
g :: [inout] The ocean’s grid structure
us :: [in] A dimensional unit scaling type
cs :: A pointer to the control structure returned by a previous call to surface_forcing_init.
sfc_state :: [in] A structure containing fields that describe the surface state of the ocean.

Call to:

mom_spatial_means::adjust_area_mean_to_zero apply_flux_adjustments check_mask_val_consistency extract_iob_stresses id_clock_forcing

subroutine mom_surface_forcing_gfdl/convert_iob_to_forces(IOB, forces, index_bounds, Time, G, US, CS, dt_forcing, reset_avg)¶

This subroutine translates the Ice_ocean_boundary_type into a MOM mechanical forcing type, including changes of units, sign conventions, and putting the fields into arrays with MOM-standard halos.

Parameters:

iob :: [in] An ice-ocean boundary type with fluxes to drive
forces :: [inout] A structure with the driving mechanical forces
index_bounds :: [in] The i- and j- size of the arrays in IOB.
time :: [in] The time of the fluxes, used for interpolating the salinity to the right time, when it is being restored.
g :: [inout] The ocean’s grid structure
us :: [in] A dimensional unit scaling type
cs :: A pointer to the control structure returned by a previous call to surface_forcing_init.
dt_forcing :: [in] A time interval over which to apply the current value of ustar as a weighted running average [T ~> s], or if 0 do not average ustar. Missing is equivalent to 0.
reset_avg :: [in] If true, reset the time average.

Call to:

apply_force_adjustments extract_iob_stresses id_clock_forcing

subroutine mom_surface_forcing_gfdl/extract_iob_stresses(IOB, index_bounds, Time, G, US, CS, taux, tauy, ustar, gustless_ustar, mag_tau, gustless_mag_tau, tau_halo)¶

This subroutine extracts the wind stresses and related fields like ustar from an Ice_ocean_boundary_type into optional argument arrays, including changes of units, sign conventions, and putting the fields into arrays with MOM-standard sized halos.

Parameters:

iob :: [in] An ice-ocean boundary type with fluxes to drive
index_bounds :: [in] The i- and j- size of the arrays in IOB.
time :: [in] The time of the fluxes, used for interpolating the salinity to the right time, when it is being restored.
g :: [inout] The ocean’s grid structure
us :: [in] A dimensional unit scaling type
cs :: A pointer to the control structure returned by a previous call to surface_forcing_init.
taux :: [inout] The zonal wind stresses on a C-grid [R Z L T-2 ~> Pa].
tauy :: [inout] The meridional wind stresses on a C-grid [R Z L T-2 ~> Pa].
ustar :: [inout] The surface friction velocity [Z T-1 ~> m s-1].
gustless_ustar :: [out] The surface friction velocity without
mag_tau :: [inout] The magintude of the wind stress at tracer points
gustless_mag_tau :: [out] The magintude of the wind stress at tracer points
tau_halo :: [in] The halo size of wind stresses to set, 0 by default.

Call to:

mom_error_handler::mom_error

Called from:

convert_iob_to_fluxes convert_iob_to_forces

subroutine mom_surface_forcing_gfdl/apply_flux_adjustments(G, US, CS, Time, fluxes)¶

Adds thermodynamic flux adjustments obtained via data_override Component name is ‘OCN’ Available adjustments are:

hflx_adj (Heat flux into the ocean [W m-2])
sflx_adj (Salt flux into the ocean [kg salt m-2 s-1])
prcme_adj (Fresh water flux into the ocean [kg m-2 s-1])

Parameters:

g :: [inout] Ocean grid structure
us :: [in] A dimensional unit scaling type
cs :: Surface forcing control structure
time :: [in] Model time structure
fluxes :: [inout] Surface fluxes structure

Called from:

convert_iob_to_fluxes

subroutine mom_surface_forcing_gfdl/apply_force_adjustments(G, US, CS, Time, forces)¶

Adds mechanical forcing adjustments obtained via data_override Component name is ‘OCN’ Available adjustments are:

taux_adj (Zonal wind stress delta, positive to the east [Pa])
tauy_adj (Meridional wind stress delta, positive to the north [Pa])

Parameters:

g :: [inout] Ocean grid structure
us :: [in] A dimensional unit scaling type
cs :: Surface forcing control structure
time :: [in] Model time structure
forces :: [inout] A structure with the driving mechanical forces

Call to:

mom_error_handler::mom_error

Called from:

convert_iob_to_forces

subroutine mom_surface_forcing_gfdl/forcing_save_restart(CS, G, Time, directory, time_stamped, filename_suffix)¶

Save any restart files associated with the surface forcing.

Parameters:

cs :: A pointer to the control structure returned by a previous call to surface_forcing_init
g :: [inout] The ocean’s grid structure
time :: [in] The current model time
directory :: [in] The directory into which to write the restart files
time_stamped :: [in] If true, the restart file names include a unique time stamp. The default is false.
filename_suffix :: [in] An optional suffix (e.g., a time- stamp) to append to the restart file names.

Call to:

mom_restart::save_restart

Called from:

ocean_model_mod::ocean_model_restart ocean_model_mod::ocean_model_save_restart

subroutine mom_surface_forcing_gfdl/surface_forcing_init(Time, G, US, param_file, diag, CS, wind_stagger)¶

Initialize the surface forcing, including setting parameters and allocating permanent memory.

Parameters:

time :: [in] The current model time
g :: [in] The ocean’s grid structure
us :: [in] A dimensional unit scaling type
param_file :: [in] A structure to parse for run-time parameters
diag :: [inout] A structure that is used to regulate diagnostic output
cs :: A pointer that is set to point to the control structure for this module
wind_stagger :: [in] If present, the staggering of the winds that are being provided in calls to update_ocean_model

Call to:

mom_get_input::get_mom_input id_clock_forcing mom_error_handler::mom_error mom_restart::restart_init_end mom_restart::restore_state mom_string_functions::uppercase

subroutine mom_surface_forcing_gfdl/surface_forcing_end(CS, fluxes)¶

Clean up and deallocate any memory associated with this module and its children.

Parameters:

cs :: A pointer to the control structure returned by a previous call to surface_forcing_init, it will be deallocated here.
fluxes :: [inout] A structure containing pointers to all possible mass, heat or salt flux forcing fields. If present, it will be deallocated here.

subroutine mom_surface_forcing_gfdl/ice_ocn_bnd_type_chksum(id, timestep, iobt)¶

Write out a set of messages with checksums of the fields in an ice_ocean_boundary type.

Parameters:

id :: [in] An identifying string for this call
timestep :: [in] The number of elapsed timesteps
iobt :: [in] An ice-ocean boundary type with fluxes to drive the

Call to:

mom_io::stdout_if_root

subroutine mom_surface_forcing_gfdl/check_mask_val_consistency(val, mask, i, j, varname, G)¶

Check the values passed by IOB over land are zero.

Parameters:

val :: [in] value of flux/variable passed by IOB [various]
mask :: [in] value of ocean mask [nondim]
i :: [in] model grid cell indices
j :: [in] model grid cell indices
varname :: [in] variable name
g :: [in] The ocean’s grid structure

Call to:

mom_error_handler::mom_error

Called from:

convert_iob_to_fluxes