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

module flux_exchange

Contact:   Bruce Wyman
Reviewers: 
Change History:  WebCVS Log
Last Modified:  $Date: 2002/02/22 19:13:00 $


OVERVIEW

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.


OTHER MODULES USED

   atmos_model_mod
     ice_model_mod
   ocean_model_mod
    land_model_mod
  surface_flux_mod
 monin_obukhov_mod
         xgrid_mod
  diag_manager_mod
  time_manager_mod
sat_vapor_pres_mod
 diag_integral_mod
     utilities_mod
     constants_mod
           mpp_mod
   mpp_domains_mod

PUBLIC INTERFACE

    use flux_exchange_mod [, only: flux_exchange_init,   &
                                   sfc_boundary_layer,   &
                                   generate_sfc_xgrid,   &
                                   flux_down_from_atmos, &
                                   flux_up_to_atmos,     &
                                   flux_land_to_ice,     &
                                   flux_ice_to_ocean,    &
                                   flux_ocean_to_ice ]

flux_exchange_init:
Initializes the interpolation routines and diagnostics.
generate_sfc_xgrid:
Optimizes the exchange grids by eliminating land and ice partitions with no data.
sfc_boundary_layer:
Computes explicit fluxes as well as derivatives that will be used to compute an implicit flux correction.
flux_down_from_atmos:
Returns fluxes and derivatives corrected for the implicit treatment of atmospheric diffusive fluxes, as well as the increments in the temperature and specific humidity of the lowest atmospheric layer due to all explicit processes as well as the diffusive fluxes through the top of this layer.
flux_up_to_atmos:
Corrects the fluxes for consistency with the new surface temperatures in land and ice models. Final increments for temperature and specific humidity in the lowest atmospheric layer are computed and returned to the atmospheric model so that it can finalize the increments in the rest of the atmosphere.
flux_ice_to_ocean:
Takes the ice model state (fluxes at the bottom of the ice) and interpolates it to the ocean model grid.
flux_ocean_to_ice:
Takes the ocean model state and interpolates it onto the bottom of the ice.
flux_land_to_ice:
Cnservative transfer of water and snow discharge from the land model to sea ice/ocean model.


PUBLIC DATA

None.


PUBLIC ROUTINES

Note:

All arguments below are assumed to be real unless otherwise stated. The following suffixes for variable names will designate which component model grid the field is on.

          _atm     atmospheric model, dimension(:,:)
          _ocean   ocean model,       dimension(:,:)
          _land    land model,        dimension(:,:,:)
          _ice     ice model,         dimension(:,:,:)

The first two dimensions are assumed to be longitude and latitude. The third dimension (for the land and ice models) is for partitions (e.g., different land or ice types).

For details on the defined types (atmos_boundary_data_type, land_boundary_data_type, ice_boundary_data_type, ocean_boundary_data_type) see the documentation for the individual component models or look at the developer notes below.

  1. flux_exchange_init

      subroutine flux_exchange_init ( Time, Atm, Land, Ice, Ocean, &
           atmos_land_boundary, atmos_ice_boundary, land_ice_atmos_boundary, &
           land_ice_boundary, ice_ocean_boundary, ocean_ice_boundary )
    
        type                (time_type), intent(in)  :: Time
        type (atmos_boundary_data_type), intent(in)  :: Atm
        type  (land_boundary_data_type), intent(in)  :: Land
        type   (ice_data_type), intent(in)  :: Ice
        type (ocean_data_type), intent(in)  :: Ocean
        type(atmos_land_boundary_type), intent(out) :: atmos_land_boundary
        type(atmos_ice_boundary_type), intent(out) :: atmos_ice_boundary
        type(land_ice_atmos_boundary_type), intent(out) :: land_ice_atmos_boundary
        type(land_ice_boundary_type), intent(out) :: land_ice_boundary
        type(ice_ocean_boundary_type), intent(out) :: ice_ocean_boundary
        type(ocean_ice_boundary_type), intent(out) :: ocean_ice_boundary
    
    
  2. sfc_boundary_layer

      subroutine sfc_boundary_layer ( dt, Time, Atm, Land, Ice, Boundary )
    
        real,                   intent(in)  :: dt
        type       (time_type), intent(in)  :: Time
        type (atmos_boundary_data_type), intent(in)  :: Atm
        type  (land_boundary_data_type), intent(in)  :: Land
        type   (ice_data_type), intent(in)  :: Ice
        type(land_ice_atmos_boundary_type), intent(out) :: Boundary
    

    The following quantities in the land_ice_atmos_boundary_type are computed:

     
         t_surf_atm = surface temperature (used for radiation)    (K)
         albedo_atm = surface albedo      (used for radiation)    (nondimensional)
      rough_mom_atm = surface roughness for momentum (m)
      land_frac_atm = fractional area of land beneath an atmospheric
                      grid box 
         dtaudv_atm = derivative of wind stress w.r.t. the
                      lowest level wind speed  (Pa/(m/s))
         flux_u_atm = zonal wind stress  (Pa)
         flux_v_atm = meridional wind stress (Pa)
         u_star_atm = friction velocity (m/s)
         b_star_atm = buoyancy scale    (m2/s)
    
         (u_star and b_star are defined so that u_star**2 = magnitude
           of surface stress divided by density of air at the surface, 
           and u_star*b_star = buoyancy flux at the surface)
    
  3. flux_down_from_atmos

      subroutine flux_down_from_atmos (Time, Atm, Land, Ice, Atmos_boundary, 
                                       Land_boundary, Ice_boundary )
    
        type       (time_type), intent(in)  :: Time
        type (atmos_boundary_data_type), intent(in)  :: Atm
        type  (land_boundary_data_type), intent(in)  :: Land
        type   (ice_data_type), intent(in)  :: Ice
        type(land_ice_atmos_boundary_type), intent(in) :: Atmos_boundary
        type(atmos_land_boundary_type), intent(out) :: Land_boundary
        type(atmos_ice_boundary_type),  intent(out) :: Ice_boundary
    
    

    The following elements from Atmos_boundary are used as input:

        flux_u_atm = zonal wind stress (Pa)  
        flux_v_atm = meridional wind stress (Pa)
    

    The following elements of Land_boundary are output:

       flux_t_land = sensible heat flux (W/m2)
       flux_q_land = specific humidity flux (Kg/(m2 s)
      flux_lw_land = net longwave flux (W/m2), uncorrected for
                     changes in surface temperature
      flux_sw_land = net shortwave flux (W/m2)
         dhdt_land = derivative of sensible heat flux w.r.t.
                     surface temperature (on land model grid)  (W/(m2 K)
         dedt_land = derivative of specific humidity flux w.r.t.
                     surface temperature (on land model grid)  (Kg/(m2 s K)
         drdt_land = derivative of upward longwave flux w.r.t.
                     surface temperature (on land model grid) (W/(m2 K)
        lprec_land = liquid precipitation, mass for one time step
                      (Kg/m2)
        fprec_land = frozen precipitation, mass for one time step
                      (Kg/m2)
    

    The following elements of Ice_boundary are output:

        flux_u_ice = zonal wind stress (Pa)
        flux_v_ice = meridional wind stress (Pa)
        coszen_ice = cosine of the zenith angle
    
  4. flux_land_to_ice

      subroutine flux_land_to_ice(Land, Ice, Boundary )
        type (land_boundary_data_type), intent(in) :: Land
        type ( ice_data_type), intent(in) :: Ice
        type(land_ice_boundary_type), intent(out) :: Boundary
    

    The following elements are transferred from the Land to the Land_ice_boundary:

        discharge --> runoff (kg/m2)
        discharge_snow --> calving (kg/m2)
    
  5. flux_ice_to_ocean

      subroutine flux_ice_to_ocean ( Ice, Ocean, Boundary )
    
        type (ice_data_type),   intent(in)  :: Ice
        type (ocean_data_type), intent(in)  :: Ocean
        type(ice_ocean_boundary_type), intent(inout) :: Boundary
    

    The following quantities are transferred from the Ice to the ice_ocean_boundary_type:

       flux_u = zonal wind stress (Pa)
       flux_v = meridional wind stress (Pa)
       flux_t = sensible heat flux (W/m2)
       flux_q = specific humidity flux (Kg/m2/s)
    flux_salt = salt flux (Kg/m2/s)
      flux_sw = net (down-up) shortwave flux (W/m2)
      flux_lw = net (down-up) longwave flux (W/m2)
        lprec = mass of liquid precipitation since last
                      time step (Kg/m2)
        fprec = mass of frozen precipitation since last
                time step (Kg/m2)
       runoff = mass (?) of runoff since last time step
                       (Kg/m2)
       p_surf = surface pressure (Pa)
    
  6. flux_ocean_to_ice

      subroutine flux_ocean_to_ice ( Ocean, Ice, Boundary )
    
        type (ocean_data_type), intent(in)  :: Ocean
        type (ice_data_type),   intent(in)  :: Ice
        type(ocean_ice_boundary_type), intent(inout) :: Boundary
    

    The following quantities are transferred from the Ocean to the ocean_ice_boundary_type:

        t_surf = surface temperature (deg K)
        frazil = frazil (???)
        u_surf = zonal ocean current/ice motion (m/s)
        v_surf = meridional ocean current/ice motion (m/s)
    
  7. generate_sfc_xgrid

      subroutine generate_sfc_xgrid( Land, Ice )
        type(land_boundary_data_type), intent(in) :: Land
        type(ice_data_type), intent(in)           :: Ice
    
  8. flux_up_to_atmos

      subroutine flux_up_to_atmos ( Time, Land, Ice, Boundary )
    
        type       (time_type), intent(in)  :: Time
        type  (land_boundary_data_type), intent(in)  :: Land
        type   (ice_data_type), intent(in)  :: Ice
        type(land_ice_atmos_boundary_type), intent(out) :: Boundary
    
     in:       Time   = current time [time_type]
               Land   =            [land_boundary_data_type]
               Ice    =             [ice_boundary_data_type]
    
     The following elements of the land_ice_atmos_boundary_type are computed:
        dt_t  = temperature change at the lowest
                 atmospheric level (deg k)
        dt_q  = specific humidity change at the lowest
                 atmospheric level (kg/kg)
    

NAMELIST

&flux_exchange_nml

z_ref_heat
reference height (meters) for temperature and relative humidity diagnostics (t_ref,rh_ref,del_h,del_q)
[real, default: z_ref_heat = 2.]
z_ref_mom
reference height (meters) for momentum diagnostics (u_ref,v_ref,del_m)
[real, default: z_ref_mom = 10.
]


DIAGNOSTIC FIELDS

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

Diagnostic fields for module name identifier: flux

   field name      field description (units)
   ----------      -------------------------

   land_mask       fractional amount of land (none)     <-- STATIC
   glac_mask       fractional amount of glacier (none)  <-- STATIC
   ice_mask        fractional amount of sea ice (none)
   wind            wind speed for flux calculations (m/s)
   drag_moist      drag coeff for moisture (none)
   drag_heat       drag coeff for heat (none)
   drag_mom        drag coeff for momentum (none)
   rough_moist     surface roughness for moisture (m)
   rough_heat      surface roughness for heat (m)
   rough_mom       surface roughness for momentum (m)
   u_star          friction velocity (m/s)
   b_star          buoyancy scale (m/s2)
   tau_x           zonal wind stress (pa)
   tau_y           meridional wind stress (pa)
   t_surf          surface temperature (deg_k)
   shflx           sensible heat flux (w/m2)
   evap            evaporation rate (kg/m2/s)
   lwflx           net (down-up) longwave flux (w/m2)
   t_atm           temperature at btm level (deg_k)
   u_atm           u wind component at btm level (m/s)
   v_atm           v wind component at btm level (m/s)
   rh_ref          relative humidity at ref height (deg_k)
   t_ref           temperature at ref height (deg_k)
   u_ref           u wind component at ref height (m/s)
   v_ref           v wind component at ref height (m/s)
   del_q           ref height interp factor for specific humidity (none)
   del_h           ref height interp factor for heat (none)
   del_m           ref height interp factor for momentum (none)
Notes:

  1. del_q, del_h, or del_m cannot be output unless rh_ref, t_ref, u_ref, or v_ref have been specified.
  2. All fields are output on the two-dimensional (x-y) atmospheric grid.


DATA SETS

The grid_spec.nc file is read by flux_exchange_init to set up the xmap_sfc and xmap_runoff exchange grids.


ERROR MESSAGES

FATAL ERROR in flux_exchange
must call flux_exchange_init first
flux_exchange_init has not been called before calling sfc_boundary_layer.

FATAL ERROR in switch_surf_diff_type_order in vert_diff_mod
arguments have the wrong order
This error should not occur unless the user has modified the code. Check with the developer if necessary.


REFERENCES

None.


COMPILER SPECIFICS

None.


PRECOMPILER OPTIONS (or PORTABILITY)

None.


LOADER OPTIONS (or ACQUIRING SOURCE)

None.


KNOWN BUGS

None.


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 thorugh 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


FUTURE PLANS

Run-time configuration of exchange quantities.