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 Ocean-Atmos Concurrent Coupling  #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. Add remap to coupler_put! #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