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
Expand | ||
---|---|---|
| ||
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
Use the symbols below (copy and paste) to indicate if the section is in progress or done or not started. |
...
Page Properties | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||
|
Expand | |||
---|---|---|---|
| |||
|
Title:
...
B1_Soil Erosion Model Development
Requirements and Design
...
E3SM Land Group
Date:
...
Summary
Requirements
Requirement: name-of-requirement-here
Date last modified: // date
Contributors: @ name (add your name to this list if it does not appear)
Each requirement is to be listed under a ”section” heading, as there will be a one-to-one correspondence between requirements, design, proposed imple- mentation and testing. Requirements should not discuss technical software issues, but rather focus on model capability. To the extent possible, require- ments should be relatively independent of each other, thus allowing a clean design solution, implementation and testing plan.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)
For each requirement, there is a design solution that is intended to meet that requirement. Design solutions can include detailed technical discussions of PDEs, algorithms, solvers and similar, as well as technical discussion of performance issues. In general, this section should steer away from a detailed discussion of low-level software issues such as variable declarations, interfaces and sequencing.
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)
This section should detail the plan for implementing the design solution for requirement XXX. In general, this section is software-centric with a focus on software implementation. Pseudo code is appropriate in this section. Links to actual source code are appropriate. Project management items, such as svn branches, timelines and staffing are also appropriate. How do we typeset pseudo code?- Implement the improved Morgan soil erosion model in ELM
- Implement erosion induced C yield in ELM
- Implement erosion induced N and P yield in ELM
Requirements
Requirement: Represent soil erosion and erosion-induced biogeochemical fluxes in the E3SM land model
Date last modified:
Contributors: Zeli Tan, Ruby Leung, Hongyi Li, Teklu Tesfa
Many studies have indicated that initiated by soil erosion, huge amounts of C, N and P are transported from land to rivers and eventually oceans. These biogeochemical fluxes could have significant impacts on the global biogeochemical cycles and have rarely been represented by the current generation of ESMs.
Algorithmic Formulations and Design
Design Solution: Represent soil erosion and sediment yield using the improved Morgan model
Date last modified:
Contributors: Zeli Tan, Ruby Leung, Hongyi Li, Teklu Tesfa
The details of algorithmic formulations can be found in the supplementary material's Section S5.1 of Tan et al. (2018). In brief, the rainfall-driven erosion F, runoff-driven erosion H and transport capacity of overland flow Tc are parameterized by Eq. (1), Eq. (2) and Eq. (3), respectively. Sediment yield is the smaller value between F + Q and Tc.
F = 1e-3 * c1 * K * (KE_DT + KE_LD) (1)
H = 19.1e-3 * c2 * Z * Qs^1.5 * sin(SLP) * (1-GC) (2)
Tc = 19.1e-3 * c3 * C * Qs^2 * sin(SLP) (3)
where c1, c2 and c3 are scale parameters for calibration, K is the erodibility of the soil by rainfall, KE_DT and KE_LD are the kinetic energy of the direct throughfall and leaf drainage, respectively, Z is soil detachability by runoff, Qs is surface runoff, SLP is the average slope of upland area, and GC is ground cover in fraction.
Tan, Z., Leung, L. R., Li, H. Y., & Tesfa, T. (2018). Modeling Sediment Yield in Land Surface and Earth System Models: Model Comparison, Development, and Evaluation. Journal of Advances in Modeling Earth Systems, 10, 2192-2213.
Design Solution: Represent erosion induced C yield
Date last modified:
Contributors: Zeli Tan, Ruby Leung, Hongyi Li, Teklu Tesfa, Qing Zhu
The C yield is calculated by multiplying sediment yield with SOC content in surface soils. The loss of SOC from the soil column is modeled following the method of Naipal et al. (2018). SOC content is simulated by ELM BGC.
Naipal, V.; Ciais, P.; Wang, Y.; Lauerwald, R.; Guenet, B.; Van Oost, K. Global soil organic carbon removal by water erosion under climate change and land use change during AD 1850–2005. Biogeosciences 2018, 15, 4459–4480.
Design Solution: Represent erosion induced N and P yield
Date last modified:
Contributors: Zeli Tan, Ruby Leung, Hongyi Li, Teklu Tesfa, Qing Zhu
The N and P yield are calculated by multiplying C yield with C/N (Eq. 4) and C/P ratios (Eq. 5) in riverine sediments (Beusen et al., 2005). The loss of N and P from the soil column is modeled following the method of Naipal et al. (2018).
PNc = 0.116 * POCc - 0.019 (4)
PPm = POCm^1.002 / 22.1536 (5)
Beusen, A. H. W.; Dekkers, A. L. M.; Bouwman, A. F.; Ludwig, W.; Harrison, J. Estimation of global river transport of sediments and associated particulate C, N, and P. Global Biogeochem. Cycles 2005, 19, GB4S05.
Naipal, V.; Ciais, P.; Wang, Y.; Lauerwald, R.; Guenet, B.; Van Oost, K. Global soil organic carbon removal by water erosion under climate change and land use change during AD 1850–2005. Biogeosciences 2018, 15, 4459–4480.
Design Implementation
Implementation: Represent soil erosion and sediment yield using the improved Morgan model
Date last modified:
Contributors: Zeli Tan
Implement the soil erosion model in components/clm/src/biogeophys/SedYieldMod.F90 and the related flux variables are implemented in components/clm/src/biogeophys/SedFluxType.F90.
Implementation: Represent erosion induced C yield
Date last modified:
Contributors: Zeli Tan
Implement erosion induced C flux in components/clm/src/biogeochem/ErosionMod.F90 and CarbonStateUpdate3Mod.F90 is modified for the impact of C flux on soil C pools. New C flux variables are added in components/clm/src/data_types/ColumnDataType.F90.
Implementation: Represent erosion induced N and P yield
Date last modified:
Contributors: Zeli Tan
Implement erosion induced N and P flux in components/clm/src/biogeochem/ErosionMod.F90 and NitrogenStateUpdate3Mod.F90 and PhosphorusStateUpdate3Mod.F90 are modified for the impact of N and P fluxes on soil N and P pools. New N and P flux variables are added in components/clm/src/data_types/ColumnDataType.F90.
Figure 1. A schematic of the coupled ELM-Erosion model. The rectangles grouped in the pink box represent hydrologic fluxes (blue), vegetation conditions (green) and soil biogeochemistry (yellow) that are simulated by the E3SM land model (ELM). On the upper right of the pink box, the symbols represent the calculation of rainfall-driven erosion, runoff-driven erosion, sediment transport capacity and sediment yield (the smaller value of total erosion and transport capacity) by the improved Morgan model. On the lower right of the pink box, the symbols represent the calculating of erosional biogeochemical fluxes in ELM using the simulated sediment flux.
Planned Verification and Unit Testing
Verification and Unit Testing:
short-desciption-of-testing-hereE3SM Developers test suite and also expert review
Date last modified:
Contributors:
(add your name to this list if it does not appear)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?Zeli Tan
The E3SM Developers test suite was used to make unit testing with the soil erosion model turned off. In addition, the code will be submitted for expert review on the process of PR.
Planned Validation Testing
Validation Testing:
short-desciption-of-testing-hereEvaluate the code with observation data and other publications
Date last modified:
Contributors:
(add your name to this list if it does not appear)How will XXX be tested? What observational or other dataset will be used? i.e. how will be we know when we have met requirement XXX. Will these unit tests be included in the ongoing going forward?Zeli Tan
A comprehensive model validation has been made in the continental US. The validation of the model output at the global scale was briefly made by comparing with Pelletier (2012).
Pelletier, J. D. (2012), A spatially distributed model for the long-term suspended sediment discharge and delivery ratio of drainage basins, J. Geophys. Res., 117, F02028, doi:10.1029/2011JF002129.
Planned Performance Testing
Performance Testing:
short-desciption-of-testing-hereCoupled ELM erosion simulations on Cori-KNL
Date last modified:
Contributors:
(add your name to this list if it does not appear)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?Zeli Tan
The running of the soil erosion model does not depend on specific BGC scheme. But global performance will be tested using the 360x720 grid and the I20TRGSWCNPECACNTBC compset on Cori-KNL using 192 cores. The simulation period is 2001–2004.