O5.1.5 (coupler) ClimaUtilities.jl - shared utility package

[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: @LenkaNovak
• Reviewers: @kmdeck

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 ClimaUtilities.jl#2
• Add modules for each of the currently duplicated modules
  • Regridder Regridder module ClimaUtilities.jl#4
  • BCReader/FileReader FileReader module ClimaUtilities.jl#5
  • TimeManager TimeManager module ClimaUtilities.jl#6
  • Checkpointer Checkpointer module ClimaUtilities.jl#7
• Unify function interfaces across versions of modules for different packcages
• Extend module functionality for each user package
  • ClimaCoupler
  • ClimaLSM
  • ClimaAtmos
• Convert each user package to use this new shared utilities package. Add tests ensuring functionality is as desired

SDI Revision Log

2 Oct: timelines updated, @juliasloan25 will be out of town for a conference and travel 20/10/23 - 5/11/23, so timelines after this point are delayed

CC

@tapios @simonbyrne @cmbengue

Tasks

Preview Give feedback

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

[juliasloan25]

moved to ClimaUtilities.jl - see CliMA/ClimaUtilities.jl#39