Add remapping to coupler puts & gets

[jb-mackay]

Purpose and Content

Adds remapping to the coupler put! and get calls. Implements these calls in the sea breeze simulation

Benefits and Risks

Hides explicitly calling remapping operations from the user.

Next steps

The initialization phase needs reworking and reordering in order to facilitate the auto-construction of the remap operators.

Linked Issues

#44

PR Checklist

• This PR has a corresponding issue OR is linked to an SDI.
• I have followed CliMA's codebase contribution and style guidelines OR N/A.
• I have followed CliMA's documentation policy.
• I have checked all issues and PRs and I certify that this PR does not duplicate an open PR.
• I linted my code on my local machine prior to submission OR N/A.
• Unit tests are included OR N/A.
• Code used in an integration test OR N/A.
• All tests ran successfully on my local machine OR N/A.
• All classes, modules, and function contain docstrings OR N/A.
• Documentation has been added/updated OR N/A.

[jb-mackay]

Currently it is not possible to map to an exchange or intermediary grid -- any field put! in the coupler lives on the space of the simulation that puts it there.

[jb-mackay]

Currently it is not possible to map to an exchange or intermediary grid -- any field put! in the coupler lives on the space of the simulation that puts it there.

This is because of the current way the mapping is set up which uses a tag (write_sim) to specify the source space/sim when remapping. This tag also (as the name suggests) indicates which simulation has write permissions to that coupled field.

Perhaps the right solution is to remove the double usage of write_sim and add another tag like "space_name" which would be part of the remap operator name.

[jb-mackay]

This PR sets up several follow up PRs:

1. Documentation updates:
   i. Change example used to the sea breeze as this is checked by buildkite and now a cleaner example
   ii. Add DocStringExtensions to improve doc quality
2. Add a coupler_get! method that accepts a field that will be modified/filled by the coupler_get call
3. ClimaCore: introduce AbstractRemap abstract type, with concrete subtypes including LinearRemap, IdentityRemap, RLLRemap, etc.
4. Update coupler_put! to include a remap operation. This creates symmetry and more flexibility for what grid the coupling takes place on.
5. Auto-build remap operators during init phase

[kmdeck]

minor, but we should be consistent between using "atm" and "atmos", "land" and "lnd, etc.

[LenkaNovak]

This looks very neat, thanks @jb-mackay ! I added a couple of comments, both of which we can discuss when we do the interface revamp. I think this can be merged.

[LenkaNovak]

Another way of asserting that the correct models write into the right vars could be via multiple dispatch, which would allow specifying the same name to one variable in different domains (e.g. T_sfc(::atm_sim), T_sfc(::ocn_sim) etc). We can discuss this during the interface 🍐 next week.

[jb-mackay]

I'm worried that that would lead to a large number of methods for these shared variables. I think it would be better to have fewer methods that can give us flexibility. Let's discuss further.

[LenkaNovak]

I wonder if we could get away with avoiding the (simA, simB, ...) assignment, e.g. using Symbol? Again, something we can address during the next iteration. Noted down to discuss.

[jb-mackay]

Can you elaborate?

[LenkaNovak]

I guess it would be good for this to work for an arbitrary number of sims, each of which has it's own user-defined tag. Maybe the solution will become clearer next week, when we focus on the interface! :)

[jb-mackay]

bors r+

[bors]

Build succeeded:

• buildkite/climacoupler-ci
• ci 1.7 - macOS-latest
• ci 1.7 - ubuntu-latest
• ci 1.7 - windows-latest
• docbuild
• format