B6 - Plant Hydraulics Design Document

Owned by Renata McCoy
Last updated: Aug 27, 2019 by Yilin Fang
3 min read

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,   (tick) - competed, (warning) - in progress, (error) - not done


Overview table for the owner and an approver of this feature

1.Description

Plant Hydraulics
2.OwnerYilin Fang
3.Created 
4.Equ(tick)
5.Ver(tick)
6.Perf(tick)
7.Val(error)
8.Approver
9.Approved Date
V2.0
 Click here for Table of Contents ...

Table of Contents




Title: Plant Hydraulics

Requirements and Design

E3SM Watercycle Group

Date:  

Summary

The purpose of this section is to summarize what capability is to be added to the E3SM land through this design process. It should be clear what new code will do that the current code does not. Summarizing the primary challenges with respect to software design and implementation is also appropriate for this section. Finally, this statement should contain general statement with regard to what is “success.”


Requirements

Requirement: name-of-requirement-here

The PHS model needs to conform to the big leaf model.  A new namelist variable "use_hydrstress" is added to trigger this capability. This capability also requires an updated clm_params parameter file.

Date last modified:   
Contributors: Yilin Fang Ruby Leung

Algorithmic Formulations

The algorithm follows the approach in Kennedy et al. (2019), which solves vegetation water potential in the root, stem, and sunlit leaf and shaded leaf. Water stress factor BTRAN is a function of leaf water potential instead of the soil matric potential. Four steady state equations (continuity of fluxes) are solved given transpiration and soil matric potentials in each soil layer as boundary conditions. Equations can be found in Kennedy et al. (2019).

Figure 1. Plant hydraulic circuit analog schematic (Kennedy et al., 2019)

Reference:

Kennedy, D., S. Swenson, K. W. Oleson, D. M. Lawrence, R. Fisher, A. C. L. da Costa, and P. Gentine (2019), Implementing Plant Hydraulics in the Community Land Model, Version 5, J Adv Model Earth Sy, 11(2), 485-513, doi:10.1029/2018MS001500.

Design solution:

Date last modified:// date
Contributors: (add your name to this list if it does not appear)

Solution follows Kennedy et al.


Design and Implementation

Implementation:

Date last modified: // date
Contributors: (add your name to this list if it does not appear)


The implementation follows the PHS implemented by Kennedy et al. (2019) in CLM5.


Planned Verification and Unit Testing 

Verification and Unit Testing: short-desciption-of-testing-here

Date last modified:  
Contributors: (add your name to this list if it does not appear)

The E3SM Developers test suite was used to make unit testing with PHS model turned off. In addition, the code will be submitted for expert review on the process of PR.

The PHS will be tested against the point simulation published in Kennedy et al. (2019).

Planned Validation Testing 

Validation Testing: short-desciption-of-testing-here

Date last modified:
Contributors: (add your name to this list if it does not appear)


The PHS will be validated using point and global simulation.

Planned Performance Testing 

Performance Testing: short-desciption-of-testing-here

Date last modified:
Contributors: (add your name to this list if it does not appear)

Global simulation will be tested for performance.