O_25_LI Land GLC Coupling Via CIME Design Document

Owned by Stephen Price
Last updated: Oct 07, 2015
10 min read

The Design Document page provides a description of the algorithms, implementation and planned testing including unit, verification, validation and performance testing. Please read  Step 1.3 Performance Expectations that explains feature documentation requirements from the performance group point of view. 

Design Document

 Click here for instructions to fill up the table below ......

The first table in Design Document gives overview of this document, from this info the Design Documents Overview page is automatically created.

In the overview table below 4.Equ means Equations and Algorithms, 5.Ver means Verification, 6.Perf - Performance, 7. Val - Validation

  • Equations: Document the equations that are being solved and describe algorithms
  • Verification Plans: Define tests that will be run to show that implementation is correct and robust. Involve unit tests to cover range of inputs as well as benchmarks.
  • Performance expectations: Explain the expected performance impact from this development
  • Validation Plans: Document what process-based, stand-alone component, and coupled model runs will be performed, and with what metrics will be used to assess validity

Use the symbols below (copy and paste) to indicate if the section is in progress or done or not started.

In the table below 4.Equ means Equations and Algorithms, 5.Ver means Verification, 6.Perf - Performance, 7. Val - Validation,   (tick) - competed, (warning) - in progress, (error) - not done

 

Overview table for the owner and an approver of this feature

1.Description

Land-Ice Land GLC Coupling Via CIME
2.OwnerMatt Hoffman
3.Created 
4.EquN/A (coupling - no equations)
5.Ver(tick)
6.Perf(tick)
7.Val(tick)
8.Approver 
9.Approved Date 
V1.0Accepted
 Click here for Table of Contents ...

Table of Contents

 

 

 

Title: O_25_LI Land GLC Coupling Via CIME

Requirements and Design

ACME Ice-Ocean  Group

Date: 2015-9-22

Summary

The GLC model receives surface temperature and surface mass balance from the LND model.  These fields are passed from LND to the coupler on the land grid in each of N elevation classes (where typically N = 10), and then are remapped by the coupler to the ice-sheet grid before being passed to GLC.  This coupling was implemented in CESM for CISM and is available to ACME via CIME. GLC returns ice fraction, surface elevation, and upper surface heat flux to the coupler, and coupler remaps these fields to the land grid and elevation classes before sending them to LND.  In addition, GLC passes liquid and solid runoff to OCN (WHL: or ICE?) via the coupler, but this document focuses on the GLC-LND coupling. This GLC-LND functionality needs to be reproduced for MPASLI in ACME.

Requirements

The implementation of what CISM's GLC requires to work with the GLC-LND coupling in CIME can largely be seen in the GLAD modules created by Bill Sacks (Unlicensed) in CISM: https://github.com/ACME-Climate/cism-piscees/pull/35


Requirement: Fields get sent from coupler to GLC and used by GLC

Date last modified: 2015/09/21
Contributors: Matt Hoffman, Bill Sacks (Unlicensed), Jeremy Fyke (Unlicensed), William Lipscomb (Unlicensed)


The GLC component receives fields from the LND model via the coupler:
  1. qsmb - surface mass balance of glacier ice (kg/m^2/s)
  2. tsfc - surface ground temperature (deg C)

Starting with CIME, the coupler does downscaling so these fields are on the GLC grid. 

In order for the coupler to return correct values of these fields, GLC must pass to the coupler gtopo and ice_covered.  (When the ice sheet is run diagnostically (i.e., one-way 'coupling') with LND->GLC coupling only, the land model does not use gtopo or ice_covered, but the coupler will still needs this information: 1. what gtopo value to use for the downscaling; 2. ice_covered so it knows whether to send bare land SMB (from elevation class 0) or ice-covered SMB.)

glc_import_mct should be called at the beginning of a coupler interval.


Requirement: Fields get calculated by GLC sent from GLC to coupler

Date last modified: 2015/09/21
Contributors: Matt Hoffman, Bill Sacks (Unlicensed), Jeremy Fyke (Unlicensed), William Lipscomb (Unlicensed)

The GLC component needs to pass fields to the coupler:

  1. gtopo - surface elevation of each GLC grid cell (m) (state: current snapshot) 
  2. ice_covered - whether each grid cell is ice-covered [0 or 1] (state: current snapshot)  The downscaling code (lnd -> glc) currently cannot handle fractional values, because this would require sending SMB for both ice-covered and ice-free points to a single glc cell. (This could be done, it would just require some rework.)  This mask is used by the coupler to determine where to send ice sheet landunit SMB vs. bare land landunit SMB.  This mask is used by CLM to differentiate bare land and ice sheet landunit types.
  3. hflx - output heat flux (W/m^2, positive down) (flux: time-average)  From the ice-sheet point of view, this is the conducted heat flux at the upper surface. It is computed in CISM and (hopefully soon) will be computed in MPAS LI as part of the thermal calculation. From the land point of view, it is the heat flux at the base of the ice column and is treated like a geothermal heat flux. This flux is desirable for energy conservation but is not large, so I don't thing it's critical to include it. 
  4. rofi - output ice runoff (kg/m^2/s = mm H2O/s) (flux: time-average) (This is not a LND coupling, but including it here as it also needs hooking-up.)  This is currently sent to the OCN model.
  5. rofl - output liquid runoff (kg/m^2/s = mm H2O/s) (flux: time-average) (This is not a LND coupling, but including it here as it also needs hooking-up.) This is currently sent to the OCN model.
  6. ice_sheet_grid_mask - mask of ice sheet grid coverage (state: current snapshot)  This mask defines where the ice sheet model is able to handle surface mass balance, i.e., where there is ice (grounded or floating) or bare land.  It is calculated as locations where ice is present or land is present (i.e., excluding open ocean cells on the ice sheet grid).  It is used by CLM (and maybe also the coupler?) to define where SMB should be sent. 
  7. icemask_coupled_fluxes - mask of ice sheet grid coverage where we are potentially sending non-zero fluxes (state: current snapshot) This mask indicates where the ice sheet model will actually apply SMB fluxes from the coupler.  This will be identical to "ice_sheet_grid_mask" for ice sheet instances that are configured to evolve.  If an ice sheet instance is configured to not evolve, then this field should be set to 0 everywhere in that domain.  Where this is 0 the coupler knows to send those fluxes directly to the runoff model because it is implied that the ice sheet model will not be applying them there.  This mask exists only to ensure conservation in configurations that have an ice sheet instance running but not evolving.  The GLC_TWO_WAY_COUPLING xml variable is what controls how this should be handled in CLM and the ice sheet model.

The flux fields need to be accumulated/averaged properly over the coupling interval by GLC. 

Note that gtopo and ice_covered need to be updated in a TG run for qsmb, tsfc from the coupler to be correct (i.e., updated in time as the ice sheet evolves).  However, those fields are not actually passed on to the LND model as in an IG/BG run.   

glc_export_mct should be called during initialization and then at the end of a coupler interval.


Requirement: LND model configuration adapted for new GLC component and grids for IG/BG compsets

Date last modified: 2015/09/24
Contributors: Matt Hoffman, Bill Sacks (Unlicensed), Jeremy Fyke (Unlicensed), William Lipscomb (Unlicensed)

Compsets with active LND and GLC components (e.g. IG, BG) require that the land model is configured to calculate SMB and do so in the correct locations.  This is the list of required changes.  No changes to land model code are expected.

  1. CLM configured with --glc_smb option.  This lets CLM know to perform SMB calculations.  This can be confirmed by a message in the LND log file: "glc surface mass balance will be passed to ice sheet model"  This can be set up by an entry in config_definitions.xml for <entry id="GLC_SMB".../>
  2. Configure number of elevation classes.  This can be confirmed by a message in the LND log file: "glc number of elevation classes =          10"   
    Allow CLM glacier topography to evolve dynamically.  This requires CLM4.5+. This can be confirmed by a message in the LND log file:  "glc CLM glacier topography will evolve dynamically"  
  3. Set glc glacier mask file (fglcmask).  The state of this can be checked in LND log file: "glc glacier mask file = /lustre/scratch1/turquoise/mhoffman/ACME/input_data/glc/cism/griddata/glcmaskdata_0.9x1.25_Gland20km.nc"
    This is a mask on the LND grid that indicates where SMB should be calculated.  See example below for the glcmaskdata_0.9x1.25_Gland20km.nc file.      Since this is just on the LND grid, an existing mask can be used for a Greenland MPASLI simulation as long as its extent is equal to or greater than the MPASLI grid extent.  In other words, the actual GLC grid does not matter to this mask, so long as the extent of the GLC grid falls inside the masked area. 
    For ACME v1 we should support 4 masks: i) one that covers all of Greenland (regardless of what Greenland mesh is being used), ii) one that covers all of Antarctica (regardless of what AIS mesh is being used), iii) one that covers both Greenland and Antarctica, iv) one that covers the entire globe.

           

    Examples of fglcmask files used by CLM:  covering just GIS;  covering GIS + AIS
  4. Set GLC grid to be used.  The state of this can be checked in LND log file:  "glc grid for glacier mask file =     "    This is supposed to be used by CLM namelist generation scripts to set the fglcmask file so that the mask can vary depending on what ice sheet grid is being used.  Because it appears that this logic is currently broken, a good interim solution is to set the fglcmask to the GIS+AIS mask (version iii in previous item) all the time. 
  5.  The initial snow thickness affects how long it takes nonzero SMB to be generated in an IG run.  Current default is to set the 1m snow "buckets" to half full.  This means it takes a few months for them to empty in the ablation zone or fill up in the accumulation zone and results in a lag before nonzero SMB occurs of a few months to a few years.  An alternative would be to spinup the snow system (say 5 years) and then use an input file to CLM to start from that spunup initial snow thickness.  The hard-coded initial value is controlled here:  ./main/clm_initializeMod.F90:564:          h2osno_col(c) = 0.5_r8 * h2osno_max   ! 50 cm if h2osno_max = 1 m
    Because we are most interested in Antarctica in ACME v1, and Antarctica has positive surface mass balance over most of the ice sheet most of the time, setting this default to 1.0 m will allow for rapid spin-up of the SMB calculation.  Note this only affects cold starts, and is primarily done for convenience.
     

Algorithmic Formulations

Design solution: short-description-of-proposed-solution-here

Date last modified:// date
Contributors: (add your name to this list if it does not appear)

 

(Not sure this section is necessary for this as this should be a relatively straightforward software engineering problem.)

Design and Implementation

Implementation: short-desciption-of-implementation-here

Date last modified: // date
Contributors: (add your name to this list if it does not appear)

 

(Leaving this partially blank for now until requirements are more fully understood.  My intent is to get a TG case working first, than move to IG.)

 

Planned Verification and Unit Testing 

Verification and Unit Testing: land-GLC coupling, GLC-ice sheet coupling

Date last modified:  2015/9/22
Contributors: Matt Hoffman, Jeremy Fyke (Unlicensed), William Lipscomb (Unlicensed), Stephen Price

 

Confirm that the land model is passing the surface mass balance (SMB) to GLC (in the coupler) and that in the coupler, GLC is downscaling the SMB to the ice sheet grid.

The Greenland SMB plot below confirms that a verification test defined in this way has been passed.

 



Planned Validation Testing

Validation Testing: GLC-LND coupling

Date last modified:2015/09/21
Contributors: Matt Hoffman, Jeremy Fyke (Unlicensed), William Lipscomb (Unlicensed)


Testing will be a sanity check of the MPASLI field sfcMassBal as output from
  1. a TG run
  2. an IG run.

An acceptable SMB field on the land ice grid will be judged by comparison to previous SMB fields calculated using similar capabilities in CESM and by comparison to RACMO-calculated SMB fields (see reference list at the bottom of the page for publications that include these SMB fields). Spatially integrated, overall SMB will also be compared (also see the /wiki/spaces/OCNICE/pages/1867925). 



The SMB field on the MPAS mesh from the TG compset looks like:


Color range (entire data range) is:  Min: -0.000105209 Max: 7.22935e-05 kg/m^2/s   ~=   -3.63 to 2.50 m/yr

From a cursory look, this appears correct (e.g., accumulation and ablation zones resolved with proper magnitude of SMB; the LND grid imprinting from the conservative remapping is clear as expected). 

This compset is:

<COMPSET sname="TG2000_MLI"  alias="TG_MLI">2000_SATM_DLND%SCPL_SICE_SOCN_SROF_MPASLI_SWAV</COMPSET>

 

<DLND_CPLHIST_DIR      compset="2000.*_DLND%SCPL.*_MPASLI" grid="a%0.9x1.25_l%0.9x1.25_oi%gx1v6">$DIN_LOC_ROOT/lnd/dlnd7/CPLHIST_SNO/b.e10.BG20TRCN.f09_g16.002_c121001</DLND_CPLHIST_DIR>

 

<DLND_CPLHIST_CASE     compset="2000.*_DLND%SCPL.*_MPASLI" grid="a%0.9x1.25_l%0.9x1.25_oi%gx1v6">b.e10.BG20TRCN.f09_g16.002</DLND_CPLHIST_CASE>

 

<DLND_CPLHIST_YR_ALIGN compset="2000.*_DLND%SCPL.*_MPASLI" grid="a%0.9x1.25_l%0.9x1.25_oi%gx1v6">   1</DLND_CPLHIST_YR_ALIGN>

 

<DLND_CPLHIST_YR_START compset="2000.*_DLND%SCPL.*_MPASLI" grid="a%0.9x1.25_l%0.9x1.25_oi%gx1v6">1976</DLND_CPLHIST_YR_START>

 

<DLND_CPLHIST_YR_END   compset="2000.*_DLND%SCPL.*_MPASLI" grid="a%0.9x1.25_l%0.9x1.25_oi%gx1v6">2005</DLND_CPLHIST_YR_END>

This is the second year of the simulation.


I ran an IG compset with Antarctica for 1 year using daily coupling.  Using ncra I averaged the daily sfcMassBal field in the MPASLI history files to obtain an annual average (I also have monthly averages for anyone interested).  (Note this is just once year, so not a climatological norm.)  Results are:

Left: climatological mean SMB from RACMO (Ligtenberg et al., GRL, 39, 2012; Total=2493 Gt/yr).  Right: IG compset SMB averaged over year 1 of simulation (Total=4792 Gt/yr).  Colorbar is the same for both images with a range of: 0 to +1.53 m/yr ice.

So we have the right order of magnitude with grossly correct spatial trends (low accumulation in interior, high accumulation near coast) but with strong biases.

Proposed tests for Developer Test Suite

(Need to be fleshed out.)

 

  1. given pre-computed SMB passed through coupler to ice sheet (only active component is ice sheet) (~TG; this might have multiple instances for diff. ISMs):
    1. ice sheet model (ISM) runs to completion (long / short duration?)
    2. ISM restarts exactly
    3. bfb comparison to baselines

  2. land model is config. w/ multiple elevation classes (downscaling) and passing fields to coupler for purpose of SMB calc. (something like existing I, IG):
    1. compare SMB to baseline
    2. compare land surface temperature to baseline


Planned Performance Testing 

Performance Testing: GLC-LND coupling performance

Date last modified: 2015/9/22
Contributors: Stephen Price

 

Performance / cost will be assessed by running the land model for a given period of time (e.g., 1 year) both with and without the ice sheet surface mass balance calculation active. As this is a new component / capability, we have no previous metrics for performance. For CLM, the cost increase with the surface mass balance calculation vs. without was found to be ~5-10%. Here we anticipate that cost increase to be a bit larger because we are including two ice sheets (Greenland and Antarctica) vs. just one in CLM (Greenland).

 

 

References

Vizcaíno, M., W. H. Lipscomb, W. J. Sacks, J. H. van Angelen, B. Wouters, and M. R. Van Den Broeke, 2013: Greenland Surface Mass Balance as Simulated by the Community Earth System Model. Part I: Model Evaluation and 1850–2005 Results. J Climate, 26, 7793–7812, doi:10.1175/JCLI-D-12-00615.1.

Lenaerts, J. T. M., M. R. Van Den Broeke, W. J. Van De Berg, E. Van Meijgaard, and P. Kuipers Munneke, 2012: A new, high-resolution surface mass balance map of Antarctica (1979–2010) based on regional atmospheric climate modeling. Geophys. Res. Lett, 39, doi:10.1029/2011GL050713.

Ettema, J., M. R. Van Den Broeke, E. Van Meijgaard, W. J. Van De Berg, J. E. Box, and K. Steffen, 2010: Climate of the Greenland ice sheet using a high-resolution climate model – Part 1: Evaluation. The Cryosphere, 4, 511–527, doi:10.5194/tc-4-511-2010.