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. |
In the table below 4.Equ means Equations and Algorithms, 5.Ver means Verification, 6.Perf - Performance, 7. Val - Validation, - competedcompleted, - in progress, - not done
...
Page Properties | |||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||
|
Expand | |||
---|---|---|---|
| |||
|
Title: Add topographic units to the ALM data structures, as a prerequisite for orographic downscaling
Requirements and Design
ACME Land Group
Date:
Summary
Requirements
Requirement: Represent all land-atmosphere and atmosphere-land exchanges
Date last modified:
Contributors: Peter Thornton
All the needed state and flux information exchanged between land and atmosphere must be included in the data structures native at the topounit level.
Requirement: Provide for sub-grid topology and allocation
Date last modified:
Contributors: Peter Thornton
New topounit data structures must be allocated and linked to the higher (grid) and lower(landunit) levels of the ALM nested sub-grid hierarchy, and connections must be facilitated to the coupler code that receives information from and passes information to the atmosphere.
Design solution: Represent all land-atmosphere and atmosphere-land exchanges
Date last modified:
Contributors: Peter Thornton
No new algorithmic formulations are required.
Design solution: Provide for sub-grid topology and allocation
Date last modified:
Contributors: Peter Thornton
No new algorithmic formulations are required.
Design and Implementation
Implementation: Represent all land-atmosphere and atmosphere-land exchanges
Date last modified:
Contributors: Peter Thornton
Example members for data types native to the topographic unit level:
- Topographic unit energy state (top_es): near-surface air temperature.
- Topographic unit water state (top_ws): near surface air absolute humidity, glacier mass (still to be resolved – maybe this is at the soil column level for V1)
- Topographic unit energy flux (top_ef): incident shortwave radiation (direct and diffuse, visible and near IR), incident longwave radiation, outgoing shortwave (visible and near IR), outgoing longwave, latent heat flux, sensible heat flux. Placeholder for energy transported to the ground in precipitation. Momentum flux and wind speed should ideally have their own data structures, but it may be more convenient for now to leave them with the energy fluxes. In earlier CLM versions all the atmospheric forcing data were lumped together in the atm2lnd structure. As the connections between atmosphere and land become more sophisticated, it may be helpful to initiate a more regular system for keeping track of those interface states and fluxes, as suggested here.
- Topographic unit water flux (top_wf): precipitation amount (and form as rain, snow, mixed), condensation, evaporation, transpiration. Although latent heat flux is already accounted in the top_ef structure, it will be helpful to account explicitly for the gross exchanges of water mass.
- Topographic unit physical properties (top_pp): area, mean elevation, slope, and aspect. Albedo (for direct and diffuse, visible and near IR), emissivity. Roughness length for momentum transfer. Elevation angles of horizon in several cardinal directions. ID of parent gridcell. Number, type, and IDs of child landcover units.
Implementation: Provide for sub-grid topology and allocation
Date last modified:
Contributors: Peter Thornton
General points related to software implementation:
- In contrast to the deeply nested data types used in CLM4 (where most types were defined as members of a single foundational type), the proposed implementation has multiple foundational types, avoiding multiple levels of pointer indirection.
- The non-ED implementation will use the allocatable pointer architecture for data types common in both r085 and r097 tags of CLM4.5. The ED implementation can use dynamically allocated lists using the proposed architecture, without changing its basic memory management approach.
- In contrast to the CLM4.5 implementations, the proposed architecture has separate types for variables at each level of the sub-grid hierarchy. In CLM4.5 the variable name itself is used to identify the level of the sub-grid hierarchy to which it applies (e.g. waterstate_type%h2ocan_patch for patch-level canopy intercepted water). The proposed data types would intrinsically define the relevant sub-grid level (e.g. veg_ws%h2ocan for cohort-level canopy intercepted water).
- To the extent that different data type organizations are required to meet the needs of individual subroutines or model capabilities, those types can be constructed easily as collections of pointers to the foundational types. In some cases it may be necessary to have copies of constructed data types (for example to make use of GPUs, or where the deeply nested pointer arrangement of linked lists for ED implementation is causing performance issues), in which case new space allocation and copying from foundational types is also easily supported.
- The foundational types ensure that new variables added during the development process are introduced in a logical part of the sub-grid hierarchy, and that mass and energy balance can be readily verified and maintained across multiple sub-grid levels. They also make it simple to swap model functionality at logical component boundaries. For example, a new soil column representation or a new vegetation cohort representation can be introduced and evaluated easily against existing module as long as the between-level interface variable naming and meaning is maintained.
Planned Verification and Unit Testing
Verification and Unit Testing: Represent all land-atmosphere and atmosphere-land exchange
Date last modified:
Contributors: Peter Thornton
This design requirement will be verified on the basis of BFB testing. All capability of the parent model will be reproduced in the new topounit datastructure implementation.
Verification and Unit Testing: Provide for sub-grid topology and allocation
Date last modified:
Contributors: Peter Thornton
This design requirement will be verified on the basis of BFB testing and sub-region detailed output. With topounit capability in place, it should be possible to allocate multiple topounits for a single gridcell, give them all the same forcing data, and maintain BFB results. The final stage of verification for this requirement will need to wait until the Task P5 (orographic downscaling) is complete. At that point, we will be able to trace information exchange between land and atmosphere, through the coupler, to verify that correct sub-grid information is being exchanged. Results at that stage will be answer-changing.
Planned Validation Testing
Validation Testing: Add topographic units
Date last modified:
Contributors: Peter Thornton
It will not really be possible to go beyond verification for this particular development. Validation can be done only once the integration with task P5 is complete. At that stage, we expect to use a high-resolution gridded climatology to evaluate the effectiveness of the ACME orographic downscaling approach. Further details to be provided in the Design Document page for that task (add link as it becomes available).
Planned Performance Testing
Performance Testing: Add topographic units
Date last modified:
Contributors: Peter Thornton
Performance impacts of the addition of topographic units will be evaluated using the built-in timing tools while conducting verification tests described above (BFB testing). The biggest performance impact for this line of development is expected to come from the atmosphere, once the P5 task implementation is complete.
...