Generalized exchange interface

[LenkaNovak]

The Climate Modeling Alliance

Software Design Issue 📜

Purpose

We want the coupler to treat model information exchanges in a way that it is agnostic to the particular component model source.

Linking on #44

The information exchange piece of the coupler contains the following:

• combine surfaces
• regrid
• rescaling / unit conversion
• mask application (and switching off the model in masked areas)
• coordination of the timing of the exchange (not addressed here, see #260
• optional flux calculation specification

Cost/Benefits/Risks

b: a step towards seamless coupling of different model components, including Oceananigans r: this may be disruptive across the repo (this will be done in a piece-wise manner, based on a separate initial prototype, with incremental PRs)

People and Personnel

• Lead: @LenkaNovak
• Collaborators: @juliasloan25
• Reviewers: @kmdeck,

Components

• 1. Model component level: adapters for specific component model (e.g. oceananigans, slab ocean, ... ) in the experiments directory for each component model type (e.g., ocean)
     • specifying
     • exchanged state and flux fields (T_sfc, albedo, roughness, SIC, energ_fluxes, momentum_fluxes)
     • function that can perform the interrupted stepping
     • whether fluxes are calculated in this model
     • mesh and spatial discretization for regridding
     • any model subcomponents that need to be treated separately (e.g. open water, sea ice)
     • calculation of global energy
• 2. Experiment level: coupling fields functions (e.g. CplFieldInfo functions for AMIP exchanges)
• 3. Coupler Interface level: use CouplerState-like interface, with some adjustments

Inputs

• research other couplers, review past designs (e.g. #99 ), and protototype on a simple example
• implementation of new ModelExchange module
• modifying affected modules
• unit tests
• update existing GCM drivers
• new driver for diffusive column + 2 slabs
• new driver with Oceananigans

Results and Deliverables

• [ ] ModelExchange module + unit tests
• [ ] adaptation of the current modules (coupler_simulation.jl, Regridder.jl, Utilities.jl, ConservationChecker.jl), including new unit tests if needs be
• [ ] implementation in the AMIP driver
• [ ] implementation in the slabplanet driver (conservation check)
• [ ] driver for a diffusive column + 2 slabs (with ClimaCore as the only dependence)
• [ ] driver for Oceananigans + Atmos in a Cartesian domain

Task Breakdown And Schedule

• [ ] initial prototype with dummy models (ln/general_exchange_test branch, no PR here)
  • [ ] currently in review. Completion will trigger the piecewise implementation+unit tests across the code base. (24 March)
• [ ] update modules
  • [ ] CouplerSimulation (28 March)
  • [ ] Utilities (28 March)
  • [ ] Regridder (3 April)
• [ ] add user-defined adapter specifications to AMIP and ClimaCore experiments (10 April)
  • [ ] user_field_exchange.jl
  • [ ] model_init
• [ ] clean up AMIP driver (24 April)
  • [ ] comment on any remaining features not yet implemented (e.g., BCReader)
  • [ ] check surface flux calculation
  • [ ] use accumuation
  • [ ] add flux calculation per model component
  • [ ] re-ensure conservation
• [ ] add the simple diffusive column example (10 May)
• [ ] add Oceananigans coupling in a Cartesian domain (17 May)
• [ ] clean up repo (24 May)

SDI Revision Log

Future steps

• integrate changes in the BCReader
• unit checker

CC

@tapios @simonbyrne @cmbengue

[LenkaNovak]

After a series discussions and prototyping, we decided to split this SDI to #276 and #277