O1.5.2b Testing / QA overview issue

[akshaysridhar]

Purpose

Organise the development of the SurfaceFluxes.jl package (specifically with respect to quality assurance) - resolving all existing and issues into reasonable groupings that can be addressed over (at most) a sprint cycle.

Cost/Benefits/Risks

(1) Requires input from multiple users / package developers to ensure that the workflow is acceptable.
(2) Benefits: More structured development for this package given upcoming changes related to canopy / land-surface interactions, and increased model complexity through roughness sub-layers. This should also help clarify where certain physical components are handled

People and Personnel

(@ the personnel required/requested to implement the software solution)

• Lead: @akshaysridhar (Primarily responsibility for implementation)
• Collaborators: @szy21 (Atmos physics, test pipelines); @LenkaNovak (RSL models, coupler interfaces, test pipelines); @braghiere (RSL models, canopy equations, end-user) @kmdeck (RSL models, canopy equations, land-surface interactions, end-user) @charleskawczynski (Software quality, GPU compatibility review, RootSolvers support);
• Reviewers: TBD

Inputs

(1) Documentation review: Assessment of equations that inform the algorithm / code implementation.
(2) Increasing complexity in implemented equations - requires clear definition of tests before algorithm implementation.
(2) Testing: Version upgrades require (in addition to unit tests), verification across multiple packages (TurbulenceConvection.jl and ClimaAtmos.jl)

Results and deliverables

Key Results:
(1) Documented, CPU compatible toolbox for surface flux calculations for use within ClimaAtmos.jl. Clarity in default configurations for universal functions and solver options (e.g. solver tolerances and neutral boundary layer thresholds).
(2) Continued testing, and edge-case verification for root-solver convergence in iterative solutions for Monin-Obukhov length. (e.g. template for this has been applied in Thermodynamics.jl for saturation adjustment calculations.)
(3) Outcomes of surface flux calculations verified against reanalysis data. Assessment of coverage over combinations of input parameters.

Task Breakdown

Testing / Robustness / QA (There is some overlap in the scope of the issues listed here)

• Issue The noniterative solution sometimes gives large surface fluxes #71
• Issue Add physical tests for surface fluxes #73
• Issue Add Aqua tests #64
• Issues Non convergence  #35
• Issue Examples for non convergence #62
• Issue Obukhov length is sensitive to initial guess #93
• Issue Add documentation #24
• Issue Add GPU tests #22

Physical / Conceptual Improvements

• PR Update documentation #81 Documentation PR for Surface Fluxes

Proposed Delivery Date

Revision

9/11/2023: Moves GPU specific items into tracking SDI #113.
9/11/2023: Roughness sub-layer models have been moved to #84 following SURF projects.
10/23/2023: RSL tracking removed from this issue.
10/23/2023: Remove allocation test issue (Standalone issue is still open) cc @szy21

[bischtob]

@szy21 , can you review?

[szy21]

Looks good to me! @akshaysridhar Could you open an issue on the roughness sublayer and link it to this SDI?

[szy21]

SurfaceFluxes has been refactored and updated in ClimaAtmos (CliMA/ClimaAtmos.jl#2261). We don't see the non-convergence issue anymore, and the surface flux diagnostics look good. I think we can close this issue and milestone. Thanks @akshaysridhar!