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
Title: B5: Port iESM to E3SM
Requirements and Design
E3SM Land Group
Date:
Summary
- Include GCAM in the E3SM code base
- Call the GCAM component as part of the coupler timing scheme
- Pass information from GCAM to ELM on LULCC
- Pass information from GCAM to EAM on CO2 emissions
- Pass information from ELM to GCAM on NPP and HR
Requirements
Requirement: Replicate the iESM science in E3SM
Date last modified:
Contributors: Katherine Calvin (Unlicensed)
The iESM links GCAM to CESM, with the coupling primarily focused on the carbon cycle. Fossil fuel & industrial CO2 emissions AND land use/land cover change are passed from GCAM to the Earth System. Net primary productivity and heterotrophic respiration are passed back to GCAM from the land model. The exchange of information occurs every five years (the native GCAM time step). Data is aggregated/disaggregated between models (GCAM operates at regional scale and 5-year time steps; the ESM operates on a grid with 30 minute time step). Code is documented in Collins et al. (2015); a science example is provided in Thornton et al. (2017). The full iESM repository is available at: https://github.com/E3SM-Project/iESM
Collins, W. D., A. P. Craig, J. E. Truesdale, A. V. Di Vittorio, A. D. Jones, B. Bond-Lamberty, K. V. Calvin, J. A. Edmonds, S. H. Kim, A. M. Thomson, P. Patel, Y. Zhou, J. Mao, X. Shi, P. E. Thornton, L. P. Chini and G. C. Hurtt (2015). "The integrated Earth system model version 1: formulation and functionality." Geosci. Model Dev. 8(7): 2203-2219.
Thornton, P. E., K. Calvin, A. D. Jones, A. V. D. Vittorio, B. Bond-Lamberty, L. Chini, X. Shi, J. Mao, W. D. Collins, J. Edmonds, A. Thomson, J. Truesdale, A. Craig, M. L. Branstetter and G. Hurtt (2017). "Biospheric feedback effects in a synchronously coupled model of human and Earth systems." Nature Clim. Change 7: 496-500.
Requirement: Ensure that all possible configurations of E3SM & GCAM can run
Date last modified:
Contributors: Katherine Calvin (Unlicensed)
GCAM is an option that we will only need for some simulations. Additionally, we may want to run GCAM-ELM or GCAM-EAM, in addition to GCAM with the fully coupled model. We need to ensure that GCAM can be turned on and off like other components of E3SM through the definition of compsets.
Requirement: Ensure the GCAM couplings can be turned on and off
Date last modified:
Contributors: Katherine Calvin (Unlicensed)
We will need to be able to flexibly control which information is passed between GCAM and E3SM so that we can quantify the effect of these couplings. We need to ensure that the information passed to GCAM can be controlled via compsets or namelists.
Requirement: Implement the GCAM-E3SM coupling in a manner that can be extended in the future
Date last modified:
Contributors: Katherine Calvin (Unlicensed)
The phase 2 proposal includes extensions to the coupling between E3SM and GCAM. Additionally, GCAM is continually developing and we need to ensure we can incorporate those changes. Specifically, we will want to be able to adapt the coupling time step, the regional mappings, and which variables are passed. We need to ensure that the system is flexible and extensible.
Algorithmic Formulations, and Design Implementation
Design Solution: Port the iESM coupling code to E3SM and Link GCAM to E3SM via the coupler
Date last modified:
Contributors: Tim Shippert (Unlicensed), Katherine Calvin (Unlicensed)
Including the IAC component
Submodules: GCAM, and the other parts of the IAC code, are added via submodule. To minimize the amount of code reorganization, we technically have two submodules. The e3sm-integration
branch of the main GCAM code (https://github.com/JGCRI/gcam-core) is included as a submodule to the https://github.com/E3SM-Project/giac repository, which is then submoduled into E3SM. giac
includes some coupling code, in particular, the code to downscale, harmonize, and create land surface files. Ideally, we would include all of the relevant GCAM post-processing and coupling code in a single repository, but that isn't practical right now so we are using nested submodules.
<INSERT FIGURE SHOWING HOW THE IAC COUPLING WORKS>
Changes to the coupler
Changes to ELM
Changes to EAM
- Coupler modifications
- cesm_comp_mod.F90
- Set up iac vars, comp type, etc.
- modify general component function calls to include iac component
- … list function calls
- prep_lnd_init
- prep_atm_init
- RECV/run/SEND sections for iac component
- modify general component function calls to include iac component
- … list function calls
- Header: include iac modules and vars
- Mod cesm_init() function
- Mod cesm_run() function
- prep_lnd_mod.F90
- prep_lnd_calc_z2x_lx() - iac export to lnd grid, run in lnd prep
- prep_lnd_get_z2x_lx() - accessor function
- Mapping functions?
- prep_lnd_init() - include iac
- New functions
- Modify existing functions
- prep_atm_mod.F90
- prep_atm_calc_z2x_ax() - iac export to atm grid, run in atm prep
- prep_atm_get_z2x_ax() - accessor
- Mapping functions?
- prep_atm_init() - include iac
- New functions
- Modify existing functions
- ...Files currently unknown
- ...list modifications
- prep_iac_mod.F90
- prep_iac_init()
- prep_iac_accum() - accum land inputs, run in lnd post
- prep_iac_accum_avg() - average lnd accumulators
- prep_iac_calc_l2x_zx() - lnd export to iac grid
- prep_iac_mrg() - merge iac inputs
- New functions:
- Associated New functions
- cesm_comp_mod.F90
- Modified files
- Modify mod files to include iac in function files
- New files
- New iac coupler interface
- iac_comp_mct.F90
- iac_init_mct()
- iac_run_mct()
- iac_final_mct()
- New functions
- New files
- iac_comp_mct.F90
- Initialization and communications: modify modules and functions to include iac interface variables and perform iac initializations
- IACID, ALLIACID, CPLALLIACID, CPLIACID, numinst_iac
- Modify functions to work with iac
- seq_infodata_getData, seq_infodata_putData, seq_infodata_init, other functions
- iac_present, iac_prognostic, iac_phase, others
- explicit and/or bytype interface?
- seq_comm_mct.F90
- seq_infodata_mod.F90 - add iac
- Modifications to lnd and atm components
- Code modifications to use CO2 feedbacks from GCAM
- ...files and functions currently unknown
- Modifications to GCAM code
- Modify code to interact with iac/cpl interface
Design Solution: Implement compsets to activate different combinations of components
Date last modified:
Contributors:
.....description.....
.....reference.....
Design Solution: Enable couplings through namelist options
Date last modified:
Contributors:
.....description.....
.....reference.....
Design Solution: Embed algorithms for temporal & spatial resolution changes within the IAC component that are as flexible as possible
Date last modified:
Contributors:
.....description.....
.....reference.....
Planned Verification and Unit Testing
Verification and Unit Testing: Expert Review
Date last modified:
Contributors:
The named experts provided extensive review of each other's work, to verify that the design and implementations met the stated requirements. Model testing at each stage of implementation was used to verify that intended changes were correctly implemented, and that unintended changes were avoided.
Planned Validation Testing
Validation Testing: Evaluation with iESM developed diagnostic scripts
Date last modified:
Contributors: Katherine Calvin (Unlicensed), Alan Di Vittorio
The results of the ported code will be analyzed in a similar manner to that of the iESM (e.g., Thornton et al., 2017). We will not expect exact matches, since we are using a different ESM, but we can ensure the behavior matches expectations/previous experience.
Planned Performance Testing
Performance Testing: Short simulations on multiple platforms
Date last modified:
Contributors: Katherine Calvin (Unlicensed)
We do not expect GCAM to alter the performance of the coupled system, but we will perform short coupled simulations on multiple platforms to quantify the change.