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, - competed, - in progress, - not done

Overview table for the owner and an approver of this feature

1.Description	River water temperature module of MOSART
2.Owner	Hongyi Li
3.Created	11 Jun 2019
4.Equ
5.Ver
6.Perf
7.Val
8.Approver	Katherine Calvin (Unlicensed)
9.Approved Date	12 Sep 2019
V2.0

Click here for Table of Contents ...

Table of Contents

Title: Mosart Heat

Requirements and Design

E3SM BGC Group

Date: 11 Jun 2019

Summary

The stream temperature capacity is added to the E3SM BGC system. The new code simulates the advective heat fluxes from ALM into rivers and through the rivers, and heat exchanges between channel water and environments particularly atmosphere. The success of the code would be satisfactory performance evaluated against the observed stream temperature over multiple river gauges.

Requirements

Requirement: Implementing riverine heat process description on top of MOSART-water and water management.

Date last modified: 30 Jun 2019
Contributors: Hongyi Li, Ruby Leung

MOSART-heat has been developed and documented in Li et al. (2015) . Generally, MOSART-heat simulates one-way heat fluxes from ELM to rivers, two-way heat fluxes between river water and atmosphere, advective heat fluxes between river channels carried by the water fluxes, and finally the heat balance in river channels.

Li, H.-Y.*, L. Ruby Leung, T. Tesfa, N. Voisin, M. Hejazi, L. Liu, Y. Liu, J. Rice, H. Wu, and X. Yang (2015), Modeling stream temperature in the Anthropocene: An earth system modeling approach, J. Adv. Model. Earth Syst., 7, doi:10.1002/2015MS000471.

Requirement: Evaluation of MOSART-heat.

Date last modified: 30 Jun 2019

Contributors: Hongyi Li, Ruby Leung, Teklu Tesfa

MOSART-heat has been successfully evaluated over the contiguous U.S. against the observed daily stream temperature at over 320 USGS gauges. For details please refer to Li et al. (2015)

Li, H.-Y.*, L. Ruby Leung, T. Tesfa, N. Voisin, M. Hejazi, L. Liu, Y. Liu, J. Rice, H. Wu, and X. Yang (2015), Modeling stream temperature in the Anthropocene: An earth system modeling approach, J. Adv. Model. Earth Syst., 7, doi:10.1002/2015MS000471.

Algorithmic Formulations

Design solution: Riverine heat processes

Date last modified: 30 Jun 2019

Contributors: Hongyi Li, Ruby Leung

This is a completely new capacity added into E3SM/MOSART. All the heat processes are described in a physically-based way. The advective heat fluxes are estimated based on the advective water fluxes including the surface and subsurface runoff from hillslopes into the sub-network channel, from sub-network channel to main channel, and between upstrean/downstream main channels. The temperature of surface runoff is assumed to be equal to the average soil temperature (simulated by ELM) over the top 10cm soil layers. The temperature of subsurface runoff is assumed to be equal to the average soil temperature of those soil layers below the ground water table (simulated by ELM). The temperature of sub-network and main channel water is estimated based on the heat balance, including long-wave and short-wave solar radiation, sensible heat, latent heat and advective heat fluxes etc.

Design and Implementation

Implementation: Implementing riverine heat processes

Date last modified: 30 Jun 2019

Contributors: Ruby Leung, Hongyi Li, Anthony Craig

The implementation of MOSART-heat within E3SM largely follows the software engineering protocols used in E3SMv2 of MOSART, One major difference comparing to the version in Li et al. (2015) is that now MOSART is established NOT as part of ELM or CLM anymore, but a E3SM component parallel to ELM. As such, the coupling between MOSART-heat and ELM and EAM is achieved through the flux coupler directly.

Planned Verification and Unit Testing

Verification and Unit Testing: Verifying MOSART-heat

Date last modified: 03 Sep 2019

Contributors: Hongyi Li, Tian Zhou

Verification is performed by checking the fields that are passed from ELM and EAM to MOSART-heat through the flux coupler. MOSART-heat has been tested and passed the E3SM_developer tests on Compy.

Planned Validation Testing

Validation Testing: Validating MOSART-heat

Date last modified: 03 Sep 2019

Contributors: Hongyi Li, Ruby Leung

MOSART-heat has been validated over the U.S. domain against the observed stream temperature data from USGS gauges (see Li et al., 2015). The global validation against the observations also shows satisfactory results.

Li, H.-Y.*, L. Ruby Leung, T. Tesfa, N. Voisin, M. Hejazi, L. Liu, Y. Liu, J. Rice, H. Wu, and X. Yang (2015), Modeling stream temperature in the Anthropocene: An earth system modeling approach, J. Adv. Model. Earth Syst., 7, doi:10.1002/2015MS000471.

Planned Performance Testing

Performance Testing: MOSART-heat performance

Date last modified: 03 Sep 2019
Contributors: Hongyi Li

ELM-MOSART-heat has been run globally w/o water management option on Constance using 144 cores during a historical period 1972-2004. The total running time is ~47 hours with the water management option, and is ~45 hours without it.