Module flux_exchange

The flux_exchange module provides interfaces to couple the following component models: atmosphere, ocean, land, and ice. All interpolation between physically distinct model grids is handled by the exchange grid (xgrid_mod) with the interpolated quantities being conserved.

  1.This version of flux_exchange_mod allows the definition of physically independent
    grids for atmosphere, land and sea ice. Ice and ocean must share the same physical
    grid (though the domain decomposition on parallel systems may be different). 
    Grid information is input through the grid_spec file (URL). The masked region of the
    land grid and ice/ocean grid must "tile" each other. The masked region of the ice grid
    and ocean grid must be identical. 

         ATMOSPHERE  |----|----|----|----|----|----|----|----|

               LAND  |---|---|---|---|xxx|xxx|xxx|xxx|xxx|xxx|

                ICE  |xxx|xxx|xxx|xxx|---|---|---|---|---|---|

               OCEAN |xxx|xxx|xxx|xxx|---|---|---|---|---|---|

              where  |xxx| = masked grid point
         

    The atmosphere, land, and ice grids exchange information using the exchange grid xmap_sfc.

    The land and ice grids exchange runoff data using the exchange grid xmap_runoff.

    Transfer of data between the ice bottom and ocean does not require an exchange 
    grid as the grids are physically identical. The flux routines will automatically
    detect and redistribute data if their domain decompositions are different.

    To get information from the atmosphere to the ocean it must pass through the 
    ice model, first by interpolating from the atmospheric grid to the ice grid, 
    and then transferring from the ice grid to the ocean grid.
  2.Each component model must have a public defined data type containing specific 
    boundary fields. A list of these quantities is located in the NOTES of this document. 

  3.The surface flux of sensible heat and surface evaporation can be implicit functions
    of surface temperature. As a consequence, the parts of the land and sea-ice models 
    that update the surface temperature must be called on the atmospheric time step 

  4.The surface fluxes of all other tracers and of momentum are assumed to be explicit
    functions of all surface parameters 

  5.While no explicit reference in made within this module to the implicit treatment 
    of vertical diffusion in the atmosphere and in the land or sea-ice models, the 
    module is designed to allow for simultaneous implicit time integration on both 
    sides of the surface interface. 

  6.Due to #5, the diffusion part of the land and ice models must be called on the 
    atmospheric time step.
7. Any field passed from one component to another may be "faked" to a
   constant value, or to data acquired from a file, using the
   data_override feature of FMS. The fields to override are runtime
   configurable, using the text file <tt>data_table</tt> for input.
   See the data_override_mod documentation for more details.

   We DO NOT RECOMMEND exercising the data override capabilities of
   the FMS coupler until the user has acquired considerable
   sophistication in running FMS.

   Here is a listing of the override capabilities of the flux_exchange
   module:

   FROM the atmosphere boundary TO the exchange grid (in sfc_boundary_layer):
  
        t_bot, q_bot, z_bot, p_bot, u_bot, v_bot, p_surf, gust

   FROM the ice boundary TO the exchange grid (in sfc_boundary_layer):

        t_surf, rough_mom, rough_heat, rough_moist, albedo, u_surf, v_surf
     
   FROM the land boundary TO the exchange grid (in sfc_boundary_layer):

        t_surf, t_ca, q_ca, rough_mom, rough_heat, albedo

   FROM the exchange grid TO land_ice_atmos_boundary (in
   sfc_boundary_layer):

        t, albedo, land_frac, dt_t, dt_q, u_flux, v_flux, dtaudu, dtaudv,
        u_star, b_star, rough_mom
   
   FROM the atmosphere boundary TO the exchange grid (in
    flux_down_from_atmos):

        flux_sw, flux_lw, lprec, fprec, coszen, dtmass, delta_t,
        delta_q, dflux_t, dflux_q
        
   FROM the exchange grid TO the land boundary (in
    flux_down_from_atmos):

    t_flux, q_flux, lw_flux, sw_flux, lprec, fprec, dhdt, dedt, dedq,
    drdt, drag_q, p_surf
    
   FROM the exchange grid TO the ice boundary (in flux_down_from_atmos):

        u_flux, v_flux, t_flux, q_flux, lw_flux, lw_flux_dn, sw_flux,
        sw_flux_dn, lprec, fprec, dhdt, dedt, drdt, coszen, p 

   FROM the land boundary TO the ice boundary (in flux_land_to_ice):

        runoff, calving

   FROM the ice boundary TO the ocean boundary (in flux_ice_to_ocean):
 
        u_flux, v_flux, t_flux, q_flux, salt_flux, lw_flux, sw_flux,
        lprec, fprec, runoff, calving, p
        
   FROM the ocean boundary TO the ice boundary (in flux_ocean_to_ice):

        u, v, t, s, frazil, sea_level

   FROM the ice boundary TO the atmosphere boundary (in flux_up_to_atmos):

        t_surf

   FROM the land boundary TO the atmosphere boundary (in
    flux_up_to_atmos):
  
        t_ca, t_surf, q_ca

  See NOTES below for an explanation of the field names.

OTHER MODULES USED

PUBLIC INTERFACE

PUBLIC DATA

PUBLIC ROUTINES

NAMELIST

DIAGNOSTIC FIELDS

Diagnostic fields may be output to a netcdf file by specifying the module name identifier and the desired field names (given below) in file diag_table. See the documentation for diag_manager.

Diagnostic fields for module name identifier:

field name   
----------   
land_mask   
wind   
drag_moist   
drag_heat   
drag_mom   
rough_moist   
rough_heat   
rough_mom   
u_star   
b_star   
q_star   
t_atm   
u_atm   
v_atm   
q_atm   
p_atm   
z_atm   
gust   
rh_ref   
t_ref   
u_ref   
v_ref   
del_h   
del_m   
del_q   
tau_x   
tau_y   
ice_mask   
t_surf   
t_ca   
q_surf   
shflx   
evap   
lwflx

field description (units)
-------------------------
fractional amount of land (none)
wind speed for flux calculations  (m/s)
drag coeff for moisture (none)
drag coeff for heat (none)
drag coeff for momentum (none)
surface roughness for moisture (m)
surface roughness for heat (m)
surface roughness for momentum (m)
friction velocity (m/s)
buoyancy scale (m/s)
moisture scale (kg water/kg air)
temperature at btm level (deg_k)
u wind component at btm level (m/s)
v wind component at btm level (m/s)
specific humidity at btm level (kg/kg)
pressure at btm level (pa)
height of btm level (m)
gust scale (m/s)
relative humidity at ref height (percent)
temperature at ref height (deg_k)
zonal wind component at ref height (m/s)
meridional wind component at ref height (m/s)
ref height interp factor for heat (none)
ref height interp factor for momentum (none)
ref height interp factor for moisture (none)
zonal wind stress (pa)
meridional wind stress (pa)
fractional amount of sea ice (none)
surface temperature (deg_k)
canopy air temperature (deg_k)
surface specific humidity (kg/kg)
sensible heat flux (w/m2)
evaporation rate (kg/m2/s)
net (down-up) longwave flux (w/m2)

DATA SETS

ERROR MESSAGES

REFERENCES

COMPILER SPECIFICS

PRECOMPILER OPTIONS

LOADER OPTIONS

TEST PROGRAM

KNOWN BUGS

NOTES

  MAIN PROGRAM EXAMPLE
  --------------------

       DO slow time steps (ocean)

           call flux_ocean_to_ice

           call ICE_SLOW_UP


           DO fast time steps (atmos)

                call sfc_boundary_layer

                call ATMOS_DOWN

                call flux_down_from_atmos

                call LAND_FAST

                call ICE_FAST

                call flux_up_to_atmos

                call ATMOS_UP

           END DO

           call ICE_SLOW_DN

           call flux_ice_to_ocean

           call OCEAN

      END DO

   LAND_FAST and ICE_FAST must update the surface temperature

 =======================================================================

 REQUIRED VARIABLES IN DEFINED DATA TYPES FOR COMPONENT MODELS
 --------------------------------------------------------------

 type (atmos_boundary_data_type) :: Atm
 type (surf_diff_type) :: Atm%Surf_Diff

 real, dimension(:)

    Atm%lon_bnd   longitude axis grid box boundaries in radians
                  must be monotonic
    Atm%lat_bnd   latitude axis grid box boundaries in radians
                  must be monotonic

 real, dimension(:,:)

    Atm%t_bot     temperature at lowest model level
    Atm%q_bot     specific humidity at lowest model level
    Atm%z_bot     height above the surface for the lowest model level (m)
    Atm%p_bot     pressure at lowest model level (pa)
    Atm%u_bot     zonal wind component at lowest model level (m/s)
    Atm%v_bot     meridional wind component at lowest model level (m/s)
    Atm%p_surf    surface pressure (pa)
    Atm%gust      gustiness factor (m/s)
    Atm%flux_sw   net shortwave flux at the surface
    Atm%flux_lw   downward longwave flux at the surface
    Atm%lprec     liquid precipitation (kg/m2)
    Atm%fprec     water equivalent frozen precipitation (kg/m2)
    Atm%coszen    cosine of the zenith angle

   (the following five fields are gathered into a data type for convenience in passing
   this information through the different levels of the atmospheric model --
   these fields are rlated to the simultaneous implicit time steps in the
   atmosphere and surface models -- they are described more fully in
   flux_exchange.tech.ps and
   in the documntation for vert_diff_mod


    Atm%Surf_Diff%dtmass   = dt/mass where dt = atmospheric time step ((i+1) = (i-1) for leapfrog) (s)
                           mass = mass per unit area of lowest atmosphehic layer  (Kg/m2))
    Atm%Surf_Diff%delta_t  increment ((i+1) = (i-1) for leapfrog) in temperature of
                           lowest atmospheric layer  (K)
    Atm%Surf_Diff%delta_q  increment ((i+1) = (i-1) for leapfrog) in specific humidity of
                           lowest atmospheric layer (nondimensional -- Kg/Kg)
    Atm%Surf_Diff%dflux_t  derivative of implicit part of downward temperature flux at top of lowest
                           atmospheric layer with respect to temperature
                           of lowest atmospheric layer (Kg/(m2 s))
    Atm%Surf_Diff%dflux_q  derivative of implicit part of downward moisture flux at top of lowest
                           atmospheric layer with respect to specific humidity of
                           of lowest atmospheric layer (Kg/(m2 s))


 integer, dimension(4)

    Atm%axes      Axis identifiers returned by diag_axis_init for the
                  atmospheric model axes: X, Y, Z_full, Z_half.

 -----------------------------------------------

 type (land_boundary_data_type) :: Land

 real, dimension(:)

    Land%lon_bnd     longitude axis grid box boundaries in radians
                     must be monotonic
    Land%lat_bnd     latitude axis grid box boundaries in radians
                     must be monotonic

 logical, dimension(:,:,:)

    Land%mask        land/sea mask (true for land)
    Land%glacier     glacier mask  (true for glacier)

 real, dimension(:,:,:)

    Land%tile_size   fractional area of each tile (partition)

    Land%t_surf      surface temperature (deg k)
    Land%albedo      surface albedo (fraction)
    Land%rough_mom   surface roughness for momentum (m)
    Land%rough_heat  surface roughness for heat/moisture (m)
    Land%stomatal    stomatal resistance
    Land%snow        snow depth (water equivalent) (kg/m2)
    Land%water       water depth of the uppermost bucket (kg/m2)
    Land%max_water   maximum water depth allowed in the uppermost bucket (kg/m2)

 -----------------------------------------------


 type (ice_boundary_data_type) :: Ice

 real, dimension(:)

    Ice%lon_bnd       longitude axis grid box boundaries for temperature points
                      in radians (must be monotonic)
    Ice%lat_bnd       latitude axis grid box boundaries for temperature points
                      in radians (must be monotonic)
    Ice%lon_bnd_uv    longitude axis grid box boundaries for momentum points
                      in radians (must be monotonic)
    Ice%lat_bnd_uv    latitude axis grid box boundaries for momentum points
                      in radians (must be monotonic)

 logical, dimension(:,:,:)

    Ice%mask          ocean/land mask for temperature points
                        (true for ocean, with or without ice)
    Ice%mask_uv       ocean/land mask for momentum points
                        (true for ocean, with or without ice)
    Ice%ice_mask      optional ice mask (true for ice)

 real, dimension(:,:,:)

    Ice%part_size     fractional area of each partition of a temperature grid box
    Ice%part_size_uv  fractional area of each partition of a momentum grid box

    the following fields are located on the ice top grid

    Ice%t_surf        surface temperature (deg k)
    Ice%albedo        surface albedo (fraction)
    Ice%rough_mom     surface roughness for momentum (m)
    Ice%rough_heat    surface roughness for heat/moisture (m)
    Ice%u_surf        zonal (ocean/ice) current at the surface (m/s)
    Ice%v_surf        meridional (ocean/ice) current at the surface (m/s)

    the following fields are located on the ice bottom grid

    Ice%flux_u        zonal wind stress (Pa)
    Ice%flux_v        meridional wind stress (Pa)
    Ice%flux_t        sensible heat flux (w/m2)
    Ice%flux_q        specific humidity flux (kg/m2/s)
    Ice%flux_sw       net (down-up) shortwave flux (w/m2)
    Ice%flux_lw       net (down-up) longwave flux (w/m2)
    Ice%lprec         mass of liquid precipitation since last time step (Kg/m2)
    Ice%fprec         mass of frozen precipitation since last time step (Kg/m2)
    Ice%runoff        mass of runoff water since last time step (Kg/m2)

 -----------------------------------------------

 type (ocean_boundary_data_type) :: Ocean

 real, dimension(:)

    Ocean%Data%lon_bnd      longitude axis grid box boundaries for temperature
                            points on the ocean DATA GRID (radians)
    Ocean%Data%lat_bnd      latitude axis grid box boundaries for temperature
                            points on the ocean DATA GRID (radians)
    Ocean%Data%lon_bnd_uv   longitude axis grid box boundaries for momentum
                            points on the ocean DATA GRID (radians)
    Ocean%Data%lat_bnd_uv   latitude axis grid box boundaries for momentum
                            points on the ocean DATA GRID (radians)

    Ocean%Ocean%lon_bnd     longitude axis grid box boundaries for temperature
                            points on the ocean MODEL GRID (radians)
    Ocean%Ocean%lat_bnd     latitude axis grid box boundaries for temperature
                            points on the ocean MODEL GRID (radians)
    Ocean%Ocean%lon_bnd_uv  longitude axis grid box boundaries for momentum
                            points on the ocean MODEL GRID (radians)
    Ocean%Ocean%lat_bnd_uv  latitude axis grid box boundaries for momentum
                            points on the ocean MODEL GRID (radians)

      Note: The data values in all longitude and latitude grid box boundary
            array must be monotonic.

 logical, dimension(:,:)

    Ocean%Data%mask       ocean/land mask for temperature points on the ocean
                          DATA GRID (true for ocean)
    Ocean%Data%mask_uv    ocean/land mask for momentum points on the ocean
                          DATA GRID (true for ocean)

    Ocean%Ocean%mask      ocean/land mask for temperature points on the ocean
                          MODEL GRID (true for ocean)
    Ocean%Ocean%mask_uv   ocean/land mask for momentum points on the ocean
                          MODEL GRID (true for ocean)

 real, dimension(:,:)

    Ocean%t_surf_data  surface temperature on the ocean DATA GRID (deg k)

    Ocean%t_surf       surface temperature on the ocean MODEL GRID (deg k)
    Ocean%u_surf       zonal ocean current at the surface on the ocean
                       MODEL GRID (m/s)
    Ocean%v_surf       meridional ocean current at the surface on the
                       ocean MODEL GRID (m/s)
    Ocean%frazil       frazil at temperature points on the ocean MODEL GRID

`Time`	current time [time_type]
`Atm`	A derived data type to specify atmosphere boundary data. [atmos_data_type]
`Land`	A derived data type to specify land boundary data. [land_data_type]
`Ice`	A derived data type to specify ice boundary data. [ice_data_type]
`Ocean`	A derived data type to specify ocean boundary data. [ocean_data_type]

`atmos_ice_boundary`	A derived data type to specify properties and fluxes passed from atmosphere to ice. [atmos_ice_boundary_type]
`land_ice_atmos_boundary`	A derived data type to specify properties and fluxes passed from exchange grid to the atmosphere, land and ice. [land_ice_atmos_boundary_type]
`land_ice_boundary`	A derived data type to specify properties and fluxes passed from land to ice. [land_ice_boundary_type]
`ice_ocean_boundary`	A derived data type to specify properties and fluxes passed from ice to ocean. [ice_ocean_boundary_type]
`ocean_ice_boundary`	A derived data type to specify properties and fluxes passed from ocean to ice. [ocean_ice_boundary_type]

`dt`	time step. [real]
`Time`	current time [time_type]

`Atm`	A derived data type to specify atmosphere boundary data. [atmos_data_type]
`Land`	A derived data type to specify land boundary data. [land_data_type]
`Ice`	A derived data type to specify ice boundary data. [ice_data_type]
`Boundary`	A derived data type to specify properties and fluxes passed from exchange grid to the atmosphere, land and ice. [land_ice_atmos_boundary_type]

`Time`	current time [time_type]
`Land`	A derived data type to specify land boundary data. [land_data_type]
`Ice`	A derived data type to specify ice boundary data. [ice_data_type]
`Atmos_boundary`	A derived data type to specify properties and fluxes passed from exchange grid to the atmosphere, land and ice. [land_ice_atmos_boundary_type]