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
In the table below 4.Equ means Equations and Algorithms, 5.Ver means Verification, 6.Perf - Performance, 7. Val - Validation, 
- competed, 
- in progress, 
- not done
Overview table for the owner and an approver of this feature
1.Description | Land-Ice Land GLC Coupling Via CIME |
| 2.Owner | Matt Hoffman |
| 3.Created | 2015/9/21 |
| 4.Equ | N/A (coupling - no equations) |
| 5.Ver | |
| 6.Perf | |
| 7.Val | |
| 8.Approver | |
| 9.Approved Date |
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)
- qsmb - surface mass balance of glacier ice (kg/m^2/s)
- 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. MJH: I'm guessing about this - is this correct? WHL: For conservative two-way coupling, this is correct. When CISM is run diagnostically with LND->GLC coupling only, the land model does not use gtopo or ice_covered, but I think the coupler will still want this information. WJS: Yes - these are needed so the coupler knows what topo value to use for the downscaling (and it needs 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. Bill Sacks (Unlicensed), is that correct?
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:
- gtopo - surface elevation of each GLC grid cell (m) (state: current snapshot)
- ice_covered - whether each grid cell is ice-covered [0,1] (state: current snapshot?) SFP: Clarify if 0,1 are the only options or if a fractional value allowed? WHL: For GLC -> LND coupling, the values on the GLC grid (in principle) can be any number from 0 to 1, but CISM currently assumes that any ice-sheet grid cell has full or zero coverage. Does MPAS LI make the same assumption? WJS: 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.)
- hflx - output heat flux (W/m^2, positive down) (flux: time-average) MJH: Is this at the ice sheet-atmosphere boundary? SFP: This is computed in the coupler? It's not computed in the ice sheet model. WHL: 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.
- 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.) MJH: This is sent to OCN model, correct? WHL: Correct.
- 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.) MJH: Is this sent to the ROF or the OCN model? WHL: OCN.
- ice_sheet_grid_mask - mask of ice sheet grid coverage (state: current snapshot?) MJH: how does this differ from "ice_covered"? WHL: This mask describes the ice-sheet grid, or the set of locations where land ice may or may not be present, whereas "ice_covered" indicates where ice is currently present.
- icemask_coupled_fluxes - mask of ice sheet grid coverage where we are potentially sending non-zero fluxes (state: current snapshot? or consistent with the flux fields?) MJH: is there a more complete description of what this means? WHL: Bill Sacks (Unlicensed) would you have anything to add about the difference between ice_sheet_grid_mask and icemask_coupled_fluxes?
These fields need to be accumulated/averaged properly over the coupling interval by GLC. MJH: Which ones should be averaged vs. using a snapshot of the final time in the coupling interval? WHL: The rofi and rofl fluxes sent to OCN, along with hflx sent to LND, need to be averaged properly. The states gtopo and ice_covered would be snapshots, I think.
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 SFP: does this require dynamic land units then?). However, those fields are not actually passed on to the LND model as in an IG/BG run. In contrast, ice_covered is sent back to the LND model to determine where SMB calculations occur. MJH: I'm guessing about this - is this correct? WHL: In a TG run, LND is a data model and has no use for gtopo or ice_covered. Bill Sacks (Unlicensed), can you comment on whether the coupler in a TG run requires info from GLC? WJS: Yes - see above.
glc_export_mct should be called during initialization and then at the end of a coupler interval. Bill Sacks (Unlicensed), is that correct? I have implemented this, but I see one kind of strange thing that I think is correct behavior. Time 0 (which is the initial time before the model is integrated at all) has an SMB field that is whatever was in the input file (because I write out the initial state during init). However, that SMB field is not actually used in evolution because it is replaced with SMB from the coupler on the first call to glc_run_mct when the coupler fields are imported. In other words, I think the calculations are working properly, but the SMB output for time 0 does not reflect the coupler SMB.
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.
- 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".../>
- Configure number of elevation classes. This can be confirmed by a message in the LND log file: "glc number of elevation classes = 10" (MJH: This seems to be working, though I'm not sure exactly what triggers it.)
- Allow CLM glacier topography to evolve dynamically. This can be confirmed by a message in the LND log file: "glc CLM glacier topography will NOT evolve dynamically" (MJH: I don't know yet how to turn this on!)
- Set glc glacier mask file. 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 (MJH: Is that correct? Since this is just on the LND grid, could we just use this existing mask for a Greenland MPASLI simulation? In other words, it seems like the actual GLC grid does not matter to this mask, so long as the extent of the GLC grid falls inside the masked area.) - Set GLC grid to be used?? The state of this can be checked in LND log file: "glc grid for glacier mask file = " (MJH: I don't understand what this is or how it is used by CLM. Why does CLM care what the actual GLC grid is? Where is this set? In my IG run, this is blank, and I also noticed this message in the LND log file: "domain_check glcmask = 0 0" which looks bad.)
- Anything else?
Example of glc glacier mask file used by CLM
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)
MJH: I believe I've managed to get a basic implementation of a TG compset working (but still has issues with time levels and probably many other details). 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 updated version fixes an offset in the MPASLI grid (that was inherited from a wonky ice2sea CISM dataset). The SMB spatial pattern looks very good now.
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.
Proposed tests for Developer Test Suite
(Need to be fleshed out.)
- 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):
- ice sheet model (ISM) runs to completion (long / short duration?)
- ISM restarts exactly
- bfb comparison to baselines
- land model is config. w/ multiple elevation classes (downscaling) and passing fields to coupler for purpose of SMB calc. (something like existing I, IG):
- compare SMB to baseline
- 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 will be tested by running standard (?) compsets both with and without the land ice surface mass balance calculation active. As this is a new component / capability, we have no previous metrics for performance.
How will XXX be tested? i.e. how will be we know when we have met requirement XXX. Will these unit tests be included in the ongoing going forward?