next up previous contents
Next: 6 Running the Data Up: UsersGuide Previous: 4 Output Datasets   Contents


5 Data Exchanged with the Coupler

Each component model exchanges data with the coupler only. Component models have no direct connection with each other - all data is routed through the coupler. Most data is in the form of 2D fields. This data is accompanied by certain timing and control information (arrays of scalar real or integer values), such as the current simulation data and time.

5.1 Units Convention

All data exchanged conforms to this units convention:

Sign convention:
     positive value <=> downward flux

Unit convention:
     temperature   ~ Kelvin
     salt          ~ g/kg 
     velocity      ~ m/s
     pressure      ~ N/m^2 = Pa
     humidity      ~ kg/kg
     air density   ~ kg/m^3
     momentum flux ~ N/m^2
     heat flux     ~ W/m^2
     water flux    ~ (kg/s)/m^2
     salt flux     ~ (kg/s)/m^2
     coordinates   ~ degrees north or east
     area          ~ radians^2
     domain mask   ~ 0 <=> an inactive grid cell

5.2 Time Invariant Data

This section provides a list of the time invariant data exchanged between the coupler and each component model. Generally this data is the "domain" data: coordinate arrays, domain mask, cell areas, etc. It is assumed that the domain of all models is represented by a 2D array (although not necessarily a latitude/longitude grid).

5.2.1 Data Sent to Coupler

     domain data
   * grid cell's center coordinates, zonal      (degrees north)
   * grid cell's center coordinates, meridional (degrees east)
   * grid cell's four vertex coordinates, zonal      (degrees north)
   * grid cell's four vertex coordinates, meridional (degrees east)
   * grid cell area (radians squared)
   * grid cell domain mask ( 0 <=> not in active domain)
   * ni,nj: the dimensions of the underlying 2D array data structure

     time coordination data
   * ncpl: number of times per day the component will communicate (exchange 
     data) with the coupler.

     other information
   * IC flag: indicates whether the coupler should use model IC's contained
     on the coupler's restart file or IC's in the initial message sent from
     the component model.

5.2.2 Data Received from Coupler

     time coordination data
   * date, seconds: the exact time the coupler will start the simulation from.

5.3 Time Variant Data

This section provides a list of the time-evolving data sent exchanged between the coupler and the data model. Generally this is state, flux, and diagnostic quantities.

Each data model provides the coupler with a set of output fields. Output fields from a model include output states (which can be used by another component to compute fluxes) and output fluxes (fluxes that were computed within the model and which need to be exchanged with another component model.

The coupler provides each component model with input fields. Input fields sent to a model include input states (the state variables of other models, which are needed to do a flux calculation) and input fluxes (a forcing fields computed by some other component).

Flux fields sent to or from the coupler are understood to apply over the communication interval beginning when the data was received and ending when the next message is received. The data models must insure that fluxes sent to the coupler are appropriate in this context.

5.3.1 Data Received from Coupler

   * albedo: visible      , direct
   * albedo: near-infrared, direct
   * albedo: visible      , diffuse
   * albedo: near-infrared, diffuse
   * surface temperature (Kelvin)
   * snow height (m)
   * ice   fraction
   * ocean fraction
   * land  fraction  (implied by ice and ocean fractions)

   * zonal      surface stress (N/m^2)
   * meridional surface stress (N/m^2)
   * latent heat   (W/m^2)
   * sensible heat (W/m^2)
   * longwave radiation, upward (W/m^2)
   * evaporation ((kg/s)/m^2)

     diagnostic quantities
   * 2 meter reference air temperature (Kelvin)

5.3.2 Data Sent to Coupler

   * layer height (m)
   * zonal      velocity (m/s)
   * meridional velocity (m/s)
   * temperature (Kelvin)
   * potential temperature (Kelvin)
   * pressure (Pa)
   * equivalent sea level pressure (Pa)
   * specific humidity (kg/kg)
   * density humidity (kg/m^3)

   * precipitation: liquid, convective  ((kg/s)/m^2)
   * precipitation: liquid, large-scale ((kg/s)/m^2)
   * precipitation: frozen, convective  ((kg/s)/m^2)
   * precipitation: frozen, large-scale ((kg/s)/m^2)
   * longwave  radiation, downward                         (W/m^2)
   * shortwave radiation: downward, visible      , direct  (W/m^2)
   * shortwave radiation: downward, near-infrared, direct  (W/m^2)
   * shortwave radiation: downward, visible      , diffuse (W/m^2)
   * shortwave radiation: downward, near-infrared, diffuse (W/m^2)

     diagnostic quantities
   * net shortwave radiation (W/m^2)

5.3.3 How Output Fields are Derived

Data from the input data sequence is assumed to be daily average data. This data is linearly interpolated in time to get instantaneous fields, and this data is sent to the coupler. All data sent to the coupler is taken directly from the input data files, with a few exceptions (see below). The datm5 input data files are in the same format as history files created by CAM2 (normally they are created by CAM2). The derivations below are based on algorithms that the CAM2 atmosphere model would have used if it were able to put these fields on a CAM history file.

  1. (bottom layer pressure) = (surface pressure)*(hybrid coeff B) + (reference pressure)*(hybrid coeff A)

  2. (bottom layer potential pressure) = (bottom layer temperature) * ((surface pressure) / (bottom layer pressure)) ** ((dry air gas constant)/(specific heat of dry air))

  3. (bottom layer density) = (bottom layer pressure) / ((bottom layer temperature)*(dry air gas constant))

  4. It is assumed that downward longwave is missing from the data file, but that the file does contain net and upward longwave data, thus downward longwave is computed by subtracting upward from net longwave..

  5. It is assumed that rain is missing from the data file, but that the file does contain net precipitation and snow data thus rain data is computed by subtracting snow from net precipitation.

  6. If a user explicity changes the default value of namelist variable flux_swfact, all shortwave fields (net and downward) can be multiplied by an arbitrary factor. See the flux_swfact option in the Namelist section of this document.

  7. If a user explicity changes the default value of namelist variable flux_albfb, which activates the albedo feedback option, the net shortwave radiation sent to the coupler is derived using the four downward shortwave components and the four corresponding albedos received from the coupler:

shortwave_{net} = \sum\limits^4_{m=1}  
(1 - albedo^m)   *   shortwave_{down}^m

    This allows the net shortwave radiation to be more consistent with the surface albedos (e.g. sea ice extent). See the flux_albfb option in the Namelist section of this document. Note that this means that the datm does not ignore all input from the coupler - datm output to the coupler is now a function of input from the coupler.

next up previous contents
Next: 6 Running the Data Up: UsersGuide Previous: 4 Output Datasets   Contents