!===============================================================================
! SVN $Id: README 6696 2007-10-01 22:18:21Z kauff $
! SVN $URL: https://svn-ccsm-models.cgd.ucar.edu/tools/mapping/gen_domain/trunk_tags/gen_domain_071001/README $
!===============================================================================

This code reads in an ocean -> atmosphere mapping matrix file and outputs two 
domain description files, one for ocean and one for a complimentary land domain.  
Ocean fraction will be either 0 or 1, depending on the ocean domain mask, and 
land fraction will be calculated such that it is the compliment of the ocean domain.

NOTE: To get appropriate landfrac values, a conservative ocean -> atmosphere 
mapping file must be used.

Tested on tempest, bluesky (gen_domain_051011)

--------------------------------------------------------------------------------
Usage
--------------------------------------------------------------------------------

(a) compile
    unix> ./make.[IRIX64/AIX].csh 

(b) execute
    unix> gen_domain < gen_domain.nml > gen_domain.out

Note:  
  Output from gen_domain that is intended for use in a standard version of CCSM
  (ie. to be used in an out-of-the-box CCSM configuration), should be created by 
  CSEG, or in coordination with CSEG, in a standard location using standard code 
  and standard input data files.  Failure to do so will probably mean that the 
  domain files generated will not be accepted for use in a standard version of 
  CCSM.  For more information, contact CSEG.

--------------------------------------------------------------------------------
Namelist input
--------------------------------------------------------------------------------

Namelist inputs are:
  fn_in   = input mapping file name  (character string)
  fn1_out = output domain file name for _a grid, the ocean domain (character string)
  fn2_out = output domain file name for _b grid, the land  domain (character string)
  usercomment = optional, netcdf global attribute (character string)
  set_fv_pole_yc = [0,1,2] ~ optional, default = 0
  fminval = value ~ optional: filter on min landfrac value (r*8, default=0.001)
  fmaxval = value ~ optional: filter on max landfrac value (r*8, default=1.0)

A sample namelist is:
  fn_in  = '/fs/cgd/csm/mapping/maps/map_gx3v5_to_T31_aave_da_040122.nc'
  fn1_out = 'domain.ocn.gx3v5.050915.nc'
  fn2_out = 'domain.lnd.T31_gx3v5.050915.nc'
  usercomment = 'regeneration of domains because xxx'
  fminval = 0.001
  fmaxval = 1.0

--------------------------------------------------------------------------------
Notes:
--------------------------------------------------------------------------------

(a) Computation of land mask and cell fraction

    This code adds "cell fraction" data to the output domain files.
    The "cell fraction" indicates how much of each grid cell is active.
    Typically ocean models do not have fractional cells (their fraction
    is either 0 or 1), where as land models do have fractional cells.
    This code generates domain files where fn1_out has fractions of either
    0 or 1 (for grid cells that are masked or unmasked, respectively) and
    fn2_out has fractions that represent the compliment of fn1_out fraction
    data, as computed by the input mapping data.  Thus fn1_out is intended
    to be an ocean domain file and fn2_out is intended to be the complimentary
    land domain file.  Related, the input mapping data, fn_in, should be 
    a conservative mapping: ocean -> atmosphere.

    Computed land fractions will be truncated into the range [0,1] 
    after the min/max land fraction values have been documented.
    Computed land fractions that are less than fminval will be truncated to 0
    to avoid active land cells with tiny land fractions.

    The input atmosphere grid is assumed to be unmasked (global) and the land
    and atmosphere grids are assumed to be identical, except for cell fractions
    and masks.  Land cells whose fraction is zero will have land mask = 0.

(b) Fraction error reported in stdout

    In the stdout, the min/max land fraction is reported.  Land fractions should
    be in the range [0,1], but due to either unavoidable/acceptable numerical 
    errors or other avoidable/unacceptable errors (eg. bad mapping matrix data)
    this code may compute land fractions outside the range [0,1].

    *** THE USER IS RESPONSIBLE FOR EXAMINING THE STDOUT MIN/MAX LAND 
    *** FRACTION DATA AND MAKING THEIR OWN SUBJECTIVE DECISION ABOUT WHETHER 
    *** SUCH ERRORS ARE ACCEPTABLE OR NOT.

(c) The "pole fix" option

    set_fv_pole_yc = 0 => do not do the pole fix      (default)
    set_fv_pole_yc = 1 => do the pole-fix on fn1_out
    set_fv_pole_yc = 2 => do the pole-fix on fn2_out

    The "pole fix" means setting 
    yc(i,j) = -90 for j=1  (the min value of j: 1), and
    yc(i,j) =  90 for j=nj (the max value of j, the size of the j-dimension)
    regardless of what the coordinate values are in the input mapping data file.

    In other words, if the input mapping data min/max yc coordinates ARE NOT at 
    +/- 90 degrees but the desire is to have domain data with min/max yc coordinates 
    at +/- 90, the "pole fix" namelist option can be activated to accomplish this.
    This would only work for lat/lon grids, ie. grids that could be described
    by x(i) and y(j) coordinate arrays.
    
    Why?

    This option was introduced to accommodate a request by the CCSM Atmosphere 
    Model Working Group wherein they want certain finite volume grids 
    with min/max yc coordinates (latitude of grid cell "centers") at +/- 90 degrees, 
    yet they want the corresponding mapping data created for grids
    where the min/max yc coordinates ARE NOT at +/- 90 degrees, 
    (they are somewhat displaced toward the equator).  

    While this type of manipulation has been requested by the AMWG, it is not 
    required by the CCSM model, CCSM coupler, or the SCRIP map generation tool.

