!! Goals:

• Remove special land domain initialization coupling in CCSM system by having land and atmosphere models read land mask and fraction from external file (or potentially generate them internally). Add additional checks in coupler to verify grid consistency.
  !! Tasks:
• write off-line gen_landfrac tool for creating landfrac field for a specific atm/lnd and ocean/ice grid combination. Start with BK's domain generation tool. add frac field to domain file
• modify land models (clm, dlnd, dead) to read new domain file (as needed). Requires code and script mods.
• modify coupler to send landfrac, icefrac and ocnfrac to atm. Put consistency check currently done in cam back in the coupler and remove it from cam.
• modify atmosphere models (cam, datm, dead) to receive the landfrac from the coupler (in addition to the icefrac and ocnfrac already received) (DEFER)
• modify coupler, coupling, and land models to remove special land grid initialization by removing the code completely.
• On startup, as part of their domain info, each comonent will also send a fraction value ("frac") to the coupler.
  • land will send landfrac
  • atm will send 1. (DEFER)
  • ocn will send [0,1] mask value (DEFER)
  • ice will send [0,1] mask value (DEFER)
• determine grid consistency testing requirements and implement in coupler. coupler computes landfrac as now and compares- if comparison FAILS, then code stops
• test and review, coordinate commit, retest
  !! Requirements/Design for off-line landmask/frac generation code:

  General:

• The code is called "gen_domain"
• The code and script are checked into a directory in the ccsm repo call tools (parallel to scripts and models) called gen_domain and will be completely standalone
• The domain output files are designed to be created once for a specific atm resolution, ocean grid, and mapping file and then reused.
• The domain output file will be used by CLM and land data models and possibly other off-line tools.
• The domain output file will in the future be used by CAM and atmospheric data models as a follow up to this project.
• The domain output file is cdf format. It will meet ccsm and CF conventions.
• Given a mapping input file, both the source and destination domain files will be generated.

  Computation Aspects:

• The gen_domain output filenames will be set by namelist input.
• The gen_domain code computes a pair of output files containing lat, lon, area, mask, frac, and possibly other fields. frac will be derived in gen_domain. Land fraction will be a real8 array with values [0.0,1.0]. An implied mask exists where the mask is zero if landfrac is zero and the mask is one elsewhere.
• The shortname of the new variable on the domain cdf output file will be "frac.
• Landfrac computations will be consistent with current computations in frac_init in the cpl6 coupler to roundoff plus a couple orders of magnitude. Lets call that 1/1E12. It's also consistent with frac_init in terms of checking and setting min and max values including the case where if LANDFRAC < 0.001 then LANDFRAC = 0.0.
  these min, max and error values will be setable by namelist in
  gen_domain.
• The code inputs will be handled by namelist. Inputs include an ocean->atmosphere mapping file, and the output filenames. Also an optional comment, min, max, and eps value.

  SE:

• A single script will be used to build and run the code. Namelist inputs will be set in the script.
• The domain output file will be machine independent
• The gen_domain code will run on IBM bluesky, linux(pgi), and SGI(IRIX64)
• The gen_domain code does not have specific performance requirements
• The gen_domain code will run on a single PE
• The gen_domain code will not use MCT or other CCSM internal libraries
• The gen_domain code leans toward being simple to read, modify, build, and use.
• The gen_domain code build will NOT use any CCSM code or build scripts.

!! Notes:

Plan and Progress

• write off-line gen_landfrac tool (TC,BK) (Done)
• add frac field in startup coupling (TC). (Done)
• modify land models to read new landfrac field (TC with help from MV on clm) (datm6, dead are Done)
• modify coupling for land initialization (TC) (Done)
• test grid consistency in coupler (TC) (landfrac Done)
• modify coupler to send landfrac to atm and check fracs (TC) (Done)
• modify atmosphere models to receive landfrac (TC with help from BE on cam) (Defer)
• test and review, coordinate commit, retest (TC)

  Comments

• implementation of "real" fractions sent at startup can be defered in all models initially except land models. Need to remember to request component liaisons add this in the future.
• bfb backward compatability was requested. this was accomplished by adding a few lines to code in cpl6 that sets the land area equal to the atm area and then sets land frac equal to the internally computed value. these mods can be found in cpl6/main.F90 under "TC BFB LAND MOD".
• status of domain_compare. this was not changed in cpl6 even though the tolerance in the land model was much higher. the current tolerance is for masks to agree, lat/lon to agree to 1.e-2, and for areas to agree to 1.0e-1.
• status of frac_set. the landfrac is set at initialization (by land model) and then held constant. the ice fraction is assumed to be constantly changing. then things are updated as follows. on the ocn/ice grid, fi is limited by [0.,1.], fa = 1.-fi, fa is limited by [0.,1.]. on the atm/lnd grid, ice fraction is mapped and limited by [0.,1.], fo = 1.-fl-fi, fa = 1., fo is limited by [0.,1.]

  Questions

• How will we implement/develop/test portability requirement above? (can be handled quite easily using simple make scripts)
• What should be done for dead model? (same process but since dead won't read in the landfrac file, no landfrac test should be done in the cpl code, added a frac_test logical to frac_init interface) (Done)
  !! landfrac Use in CCSM:

  Process

• generate domains off-line from map file. include filtering to [0.001,1.0] as desired in frac field
• landfrac field is used for surface-data generation
• landfrac is read in by land model in CCSM, sent to coupler
• landfrac is received by coupler and compared to local computation of landfrac from domains, masks, and mapping file. they should agree. the cpl internally computed landfrac field must have the same filter applied before comparison is done.
• landfrac is used by cpl, land models, and sent to atm model.

  Concerns

• there is a strong link between the gen_domain code, the domain file, and the landfrac test in the coupler wrt the frac field and filtering. Suggest adding attributes to the frac field in the domain files indicating filtering. also will add namelist input in the gen_domain code for fminval, fmaxval.
  • since the landfrac file is "filtered", if the filter changes in the future, all landfrac fields will need to be regenerated.
  • the same filter must exist in the coupler as in the gen_landfrac code. this may be difficult to maintain if there are future changes in the filter.
    !! Checkin Process
• Start with ccsm3_1_beta04.
• cpl6 (TC/BK)
  • remove land grid coupling initialization and variables associated with it
  • update frac_init. add new optional arguments; check_frac, set_frac. use domain_l frac as starting point. check against mapped ocean mask computed internally. check to 1.0e-12 in frac value otherwise exit. reorganize frac_init marginally to take into account land frac sent from land model.
  • reorganize main.F90 initialization to reduce code and clean-up, consistent with removal of land grid coupling.
  • set land area = atm area and land frac to computed land frac in main.F90 for bfb compatability. one section of code needs to be removed (grep "TC BFB") to remove this.
  • add merge of Sx_lfrac in merge_mod.F90, new coupling field
• csm_share (TC/BK)
  • add frac to list of grid initialization fields (cpl-fields_grid_total now 8 fields)
  • clean up contract_init, add frac packing/unpacking, delete dead code.
  • initialize mask and frac to zero rather than spval for all grid cells of a domain.
  • add Sx_lfrac to cpl_fields_c2a_states
  • remove cpl_fields_ibuf_inimask variable
  • remove all references to cpl_fields_c2lg_fields and associated variables
  • modified all cpl_fields_mod files as needed (not all are tested)
  • add method, cpl_interface_contractField to return the field name for a given index. cpl_interface_contractIndex already existed to return an index for a given field.
  • merge bgc23 code into csm_share, UNICOSMP #if in shr_timer_mod to handle broken irtc on X1. added manually.
  • merge bgc23 code, SHR_CONST_PDB, manually.
  • modify code in shr_map_mod to handle SGI runtime error requesting size of an array that hasn't yet been allocated.
  • add optional arguments fracName and frac to shr_ncread_domain (untested).
  • fix some SGI compile problems with subroutine arguments that have both pointer and intent defined, remove intent.
  • remove dshr_hubInfo_iBuf_iniMask variable.
• dlnd6 (TC/BK)
  • remove references to init_mask
  • add frac and frac_r fields to data_msg.h
  • add new read of domain file in domain.F90 (temporary code), add new namelists data_dname to control.h to hold filename. use lat, lon, area, mask, and frac from domain file.
  • remove land grid coupling initialization and variables assocaited with it
• clm (TC/MV)
  • remove land grid coupling initialization and variables associated with it.
• dead (TC/BK)
  • remove land grid coupling initialization and variables associated with it
  • add initialization and send of mask and frac fields.
  • remove reference to inimask.
• scripts (TC/MV)
  • add domain files in dlnd.template for new domain files with frac
  • modify env.sgi.tempest for NETCDF_MOD env variable
• Testing:
  • A, T31_gx3v5, bluesky - bfb with beta04
  • X, T85_gx1v3, bluesky - runs but NOT bfb with beta04 (expected)
  • B, T31_gx3v5, bluesky - bfb with beta04
  • B, T42_gx1v3, bluesky - bfb with beta04
  • TER.01a.T31_gx3v5.A.bluesky - PASS
  • TER.01a.T85_gx1v3.X.bluesky - PASS
  • TER.01a.T42_gx1v3.B.bluesky - PASS
  • TER.01j.4x5_gx3v5.F.bluesky - PASS
  • TER.01a.T31_gx3v5.A.tempest - FAIL
  • TER.01a.T85_gx1v3.X.tempest - PASS
  • TER.01a.T31_gx3v5.B.tempest - PASS
• Known Problems:
  • datm7 compiles but does not run properly on tempest
  • case setups with CAM require netcdf lib pointing