L2_BeTR Design Doc

Owned by Gautam Bisht
Last updated: Sept 19, 2016 by Jinyun Tang

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


Overview table for the owner and an approver of this feature

1.Description

Integrating the Biogeochemical Transport and Reaction module into ALM

2.Owner
Jinyun Tang
3.Created
4.Equ(tick) 
5.Ver(tick)
6.Perf(tick)
7.Val(tick)
8.Approver
William Riley (Unlicensed), Peter Thornton
9.Approved Date
 
V1.0Accepted
 Click here for Table of Contents ...

Table of Contents




Title: Integrating the Biogeochemical Transport and Reaction module into ALM

Requirements and Design

ACME Land group
 Group

Date: 09/02/2015
 

Summary

Soil biogeochemistry is an integrated system that includes biogeochemical reactions occurring in the presence of multiphase transport of chemical species and biological organisms. The traditional modeling approach that treats the soil biogeochemistry as a single soil layer has proven inadequate to resolve the important processes and empirical measurements. Therefore, to enable ALM to better resolve the soil biogeochemistry and link ALM predictions with empirical measurements, we integrated the Biogeochemical Transport and Reaction (BeTR) module. 
BeTR is a highly modular code that prognoses multiphase transport for an arbitrary number of chemical species. It explicitly considers transport through multiphase diffusion, aqueous advection, arenchyma transport, and gas advection. It provides a template to build generic reaction-based soil biogeochemical formulations, and solves the multi-nutrient limitations consistently. It adopts the polymorphism design to allow ALM using multiple formulations of soil biogeochemical processes, which therefore provide hierarchical analysis on how structural difference would affect the soil biogeochemical model performances.

Requirements


The requirements for BeTR module include:

  •   An operator splitting based treatment of various transport and reaction processes. 
  •   A reaction based formulation of generic soil biogeochemical processes.
  •   A consistent numerical treatment to ensure mechanistic consistencies.

Date last modified: 09/02/2015

Contributors: Jinyun Tang
 (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:09/02/2015

Contributors: Jinyun Tang


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.

The generic mathematical formulation of BeTR is

d(Cs+Cw*theta+Cg*epsilon)/dt=diffusion+advection+R  ...(1)

where

Cs = solid phase of a given tracer

Cw= aqueous phase of a given tracer

Cg=gaseous phase of a given tracer

R = biogeochemical reactions, gas addictions, biotic and abiotic subsurface/later transport. 

The diffusion is solved using an implicit scheme, advection is used using the semi-lagrangian approach, and R is solved with ODE solvers. 


See Tang et al 2013.pdf for details of the model structure.

Design and Implementation

Implementation: short-desciption-of-implementation-here

Date last modified: 09/02/2015

Contributors: Jinyun Tang


  • ALM-BeTR is written using OOP design and installed as a separate directory under the ALM repository. 
  • ALM-BeTR includes its own code library to handle various substrate competition processes and appropriately refer to standard numerical packages, such as BLAS and LAPACK.

Planned Verification and Unit Testing 

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

Date last modified:  09/02/2015
Contributors: Jinyun Tang


  • Unit testing will be conducted to compare numerical simulations with analytical solutions. (Finished)
  • Mock test will be conducted to ensure the logical order of the model is constantly and correctly done. (Finished)
  • On/off tests will be conducted to make sure BeTR does not affect other soil biogeochemical formulations currently used in ALM. (Finished)

Planned Validation Testing 

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

Date last modified:09/02/2015
Contributors: Jinyun Tang


  • The reaction-based BeTR-BGC will be compared with the default Century-BGC in ALM. (Ongoing)
  • The output from BeTR-BGC will be benchmarked using ILAMB. (Ongoing)

    My recent testing of the BeTR-BGC indicate the numerical coupling of nitrogen between its relevant components are flawed. Therefore, the activities as indicated above will be delayed to v2. Also, since BeTR-BGC does not support P dynamics, it should not be recommended for use for ALM performance runs. 

Planned Performance Testing 

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

Date last modified:09/02/2015
Contributors: Jinyun Tang


  • The ACME timing logs will be implemented in the ALM-BeTR to obtain performance metrics and compared with that of the default ALM. (Ongoing)
  • Computational performance will be evaluated for offline and coupled global simulations. (Ongoing)