ClimaCoupler refactoring

[juliasloan25]

The Climate Modeling Alliance

Software Design Issue 📜

Purpose

We have identified various aspects of ClimaCoupler.jl that can be improved, including:

• moving code out of experiments/ and into src/
• splitting up the "AMIP" driver, which is currently the entry point for all simulations and as a result is quite complex
• allow constructing a CoupledSimulation object without explicitly supplying a config file/dict (using defaults)

These changes move towards ClimaCoupler.jl being usable as a package, rather than as an in-development piece of code mainly accessible by cloning the repository.

Cost/Benefits/Risks

• Benefits: lower barrier to entry for new users; more workflows supported; more readable code; increased test coverage; enhanced/updated documentation
• Risk: changed interfaces/workflows (will try to minimize this)
• Cost: developer time

People and Personnel

• Lead: @juliasloan25
• Collaborators: TBD
• Reviewers: TBD

Components

See the "Purpose" or "Tasks" sections for a list of components to the solution.

Inputs

The existing ClimaCoupler.jl package.

Results and Deliverables

• Maintain unchanged physical results
• Minimize code outside of src/

Tasks

• Move functions from experiments/ to src/ #1610
• Move component model code into extensions #1682
• Add ClimaCalibrate extension ClimaCalibrate Extension #1691
• Add new constructors for CoupledSimulation, which continue to support the existing interfaces, and also allow creating a simulation without a config file/dict, or by overwriting options in the constructor (similar to recent ClimaAtmos sim constructor changes)
• Use these new constructors to simplify model setup, and provide drivers for common simulation types (AMIP, CMIP, slabplanet, terraplanet, etc)
• Update docs to clearly show how to run different setups with the new interface
• Potentially move drivers to a new folder (examples? drivers?)
• Do we want to have a checked-in env without plotting deps?

SDI Revision Log

• 10 December 2025: SDI opened

CC

@tapios @cmbengue

[tapios]

Looks great! As you move forward on it, let's make sure to sync with @nefrathenrici about the atmosphere API refactor and a few simplifications coming on line with changes in surface fluxes.