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.
...
| Page Properties | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||
|
| Expand | |||
|---|---|---|---|
| |||
|
...
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 (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 I think the coupler will still want needs this information. WJS: Yes - these are needed so the coupler knows what topo : 1. what gtopo value to use for the downscaling (and it needs ; 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. 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 ,or 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, 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.)
hflx - output heat flux (W/m^2, 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. - hflx - output heat flux (W/m^2, positive down) (flux: time-average) MJH: Is this at From 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 -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 currently sent to the 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 This is currently 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.) 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.
- 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 )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 and icemask_coupled_fluxes?
- " 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 SFP: does this require dynamic land units then?). However). 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.
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):
- 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?
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.
- 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"
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" - 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
- 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.
- 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)
- a TG run
- 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.)
- 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 / 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.