O5.1.5: Generalize ClimaCoupler common functions to all component models and move to ClimaUtilities.jl

[juliasloan25]

The Climate Modeling Alliance

Software Design Issue 📜

Purpose

There are a few modules originally developed in ClimaCoupler.jl that have become duplicated in multiple packages, namely in ClimaLSM.jl and ClimaAtmos.jl. These include the Regridder and BCReader (FileReader in ClimaLSM). Instead of having this code duplicated and slightly modified in multiple places, we should move them to a central repository, e.g. a new ClimaUtilities.jl.

Cost/Benefits/Risks

• benefit: easier to maintain; we'll only need to update/extend code in one location rather than in all locations having the duplicate code
• cost: each package has slightly different use cases for these utilities, so we'll need to make them more general to handle each of these cases (more developer time required)

People and Personnel

• Lead: @juliasloan25
• Collaborators: @Sbozzolo
• Reviewers: @kmdeck @LenkaNovak @szy21

Components

• Add functionality to new package
• Extend modules to handle use cases of all packages currently using them
• Remove functionality from existing packages

Inputs

• see ClimaCoupler modules and ClimaLSM modules
  • Regridder in ClimaCoupler <--> Regridder in ClimaLSM
  • BCReader in ClimaCoupler, TimeManager in ClimaCoupler <--> FileReader in ClimaLSM
• see ClimaCoupler tests and ClimaLSM FileReader and Regridder tests

The ClimaLSM versions of these modules were originally based on the ClimaCoupler implementations, but have been modified to be more suited to ClimaLSM needs. This included generalizing function names that weren't accurate in the coupler version, as well as removing unneeded and unused (in either package) functionality.

ClimaAtmos also uses the regridding functionality in postprocessing (e.g. remap_helpers.jl) and in data reads in gravity wave tests (e.g. ogw_3d.jl). The Atmos interface has diverged somewhat from our modules, so careful consideration (and collaboration with Atmos) will be needed to come up with a sufficiently general utility.

Checkpointer is another module that could be added and generalized. It works similarly to Atmos, and would enable land to use the same checkpointing feature.

Note: diagnostics should also be unified, but this will be a larger effort led by @Sbozzolo , so we do not include it in the scope of this issue.

Results and Deliverables

We should not see performance or behavior changes, and tests should remain high quality. The major changes will be ease of maintenance of this code, as well as increased readability having these utilities in one place.

Task Breakdown And Schedule

• Create a new package, ClimaUtilities.jl, and set up the repo. set up repo #2
• Add modules for each of the currently duplicated modules, with unified/more general interfaces and comprehensive tests
  • Regridder Regridder module #4
  • BCReader/FileReader FileReader module #5
  • TimeManager TimeManager module #6
  • Checkpointer Checkpointer module #7
• Extend module functionality for each user package
  • ClimaCoupler
  • ClimaLSM
  • ClimaAtmos
• Use this new shared utilities package from each user package

SDI Revision Log

17 April 2024: SDI moved from ClimaCoupler.jl to ClimaUtilities.jl, as this is where most of the work will be implemented

CC

@tapios @simonbyrne @cmbengue

(replaces ClimaCoupler.jl SDI CliMA/ClimaCoupler.jl#367)

Tasks

Beta Give feedback

1. Create new ClimaUtilities.jl package, set up repo [18 Sept] set up repo #2
2. TimeManager module, tests [18 Sept] TimeManager module #6
3. TimeManager tested in user packages [22 Sept] #423
4. Regridder module, tests Regridder module #4
5. FileReader module, tests FileReader module #5
6. Checkpointer module, tests Checkpointer module #7

use ClimaUtilities from ClimaCoupler

Beta Give feedback

1. Use ClimaUtilities.jl CallbackManager module ClimaCoupler.jl#423
   🍃 leaf +1
   
2. Use ClimaUtilities.jl Regridder module ClimaCoupler.jl#425
   🍃 leaf +1
   
3. Use ClimaUtilities.jl FileReader module ClimaCoupler.jl#742
   🍃 leaf +1
   
4. Use ClimaUtilities.jl Checkpointer module ClimaCoupler.jl#426
   🍃 leaf +1
   
5. Add SurfaceCombiner module ClimaCoupler.jl#422
   🍃 leaf +1
   
6. replace Diagnostics module with ClimaDiagnostics ClimaCoupler.jl#954
   🍃 leaf enhancement +2
   

use ClimaUtilities from ClimaLand

Beta Give feedback

1. Use ClimaUtilities FileReading/Inputs/Regridding ClimaLand.jl#560
   breaking change +1