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, dimension(:,:), pointer Tidal energy dissipation in the bottom boundary layer that can act as a.
% gust :: real, dimension(:,:), pointer A spatially varying unresolved background gustiness that.
% ustar_tidal :: real, dimension(:,:), 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.
% allow_carbon_flux_exchange :: logical If true, allows fluxes and diagnostics of carbon in runoff.
% 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, dimension(:,:), 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, dimension(:,:), 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, dimension(:,:), 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.

[source]

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, dimension(:,:), pointer i-direction wind stress [Pa]
% v_flux :: real, dimension(:,:), pointer j-direction wind stress [Pa]
% t_flux :: real, dimension(:,:), pointer sensible heat flux [W m-2]
% q_flux :: real, dimension(:,:), pointer specific humidity flux [kg m-2 s-1]
% salt_flux :: real, dimension(:,:), pointer salt flux [kg m-2 s-1]
% excess_salt :: real, dimension(:,:), pointer salt left behind by brine rejection [kg m-2 s-1]
% lw_flux :: real, dimension(:,:), pointer long wave radiation [W m-2]
% sw_flux_vis_dir :: real, dimension(:,:), pointer direct visible sw radiation [W m-2]
% sw_flux_vis_dif :: real, dimension(:,:), pointer diffuse visible sw radiation [W m-2]
% sw_flux_nir_dir :: real, dimension(:,:), pointer direct Near InfraRed sw radiation [W m-2]
% sw_flux_nir_dif :: real, dimension(:,:), pointer diffuse Near InfraRed sw radiation [W m-2]
% lprec :: real, dimension(:,:), pointer mass flux of liquid precip [kg m-2 s-1]
% fprec :: real, dimension(:,:), pointer mass flux of frozen precip [kg m-2 s-1]
% runoff :: real, dimension(:,:), pointer mass flux of liquid runoff [kg m-2 s-1]
% runoff_carbon :: real, dimension(:,:), pointer mass flux of carbon in liquid runoff [kg m-2 s-1]
% calving :: real, dimension(:,:), pointer mass flux of frozen runoff [kg m-2 s-1]
% stress_mag :: real, dimension(:,:), pointer The time-mean magnitude of the stress on the ocean [Pa].
% ustar_berg :: real, dimension(:,:), pointer frictional velocity beneath icebergs [m s-1]
% area_berg :: real, dimension(:,:), pointer fractional area covered by icebergs [m2 m-2]
% mass_berg :: real, dimension(:,:), pointer mass of icebergs per unit ocean area [kg m-2]
% runoff_hflx :: real, dimension(:,:), pointer heat content of liquid runoff [W m-2]
% calving_hflx :: real, dimension(:,:), pointer heat content of frozen runoff [W m-2]
% p :: real, dimension(:,:), pointer pressure of overlying ice and atmosphere on ocean surface [Pa]
% mi :: real, dimension(:,:), pointer mass of ice per unit ocean area [kg m-2]
% ice_rigidity :: real, dimension(:,:), 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, dimension(:,:), 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.

[source]

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 :: fluxes [inout] A structure containing pointers to all possible mass, heat or salt flux forcing fields. Unused fields have NULL ptrs.
index_bounds :: 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 :: 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 :: 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

[source]

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 :: forces [inout] A structure with the driving mechanical forces
index_bounds :: 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 :: 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 :: reset_avg [in] If true, reset the time average.

Call to:

apply_force_adjustments extract_iob_stresses id_clock_forcing

[source]

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 :: 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 :: taux [inout] The zonal wind stresses on a C-grid [R Z L T-2 ~> Pa].
tauy :: tauy [inout] The meridional wind stresses on a C-grid [R Z L T-2 ~> Pa].
ustar :: ustar [inout] The surface friction velocity [Z T-1 ~> m s-1].
gustless_ustar :: gustless_ustar [out] The surface friction velocity without
mag_tau :: mag_tau [inout] The magintude of the wind stress at tracer points
gustless_mag_tau :: gustless_mag_tau [out] The magintude of the wind stress at tracer points
tau_halo :: 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

[source]

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 :: fluxes [inout] Surface fluxes structure

Called from:

convert_iob_to_fluxes

[source]

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 :: forces [inout] A structure with the driving mechanical forces

Call to:

mom_error_handler::mom_error

Called from:

convert_iob_to_forces

[source]

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 :: directory [in] The directory into which to write the restart files
time_stamped :: time_stamped [in] If true, the restart file names include a unique time stamp. The default is false.
filename_suffix :: 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

[source]

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 :: param_file [in] A structure to parse for run-time parameters
diag :: 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 :: 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

[source]

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 :: fluxes [inout] A structure containing pointers to all possible mass, heat or salt flux forcing fields. If present, it will be deallocated here.

[source]

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: