The Climate Modeling Alliance

Software Design Issue 📜

Purpose

Right now the integrated land model is unstable in coupled runs. We've isolated this to the solve of canopy temperature/fluxes via the following tests:

• integrated land + prescribed atmosphere + implicit solve of canopy T+fluxes together: stable
• integrated land + prescribed atmosphere + explicit solve of canopy T: unstable (even with small dt=120s)
• integrated land + coupled ClimaAtmos atmosphere, explicit solve of canopy T: unstable
• integrated land (no canopy) + coupled ClimaAtmos: stable

To make this setup stable, we need to enable a way to implicitly solve for canopy T and fluxes together. This is already done in offline land model runs.

Hopefully, the same (or a similar) approach can be applied to coupling ClimaSeaIce.jl to stabilize that configuration too. cc @simone-silvestri

Cost/Benefits/Risks

Costs: developer time, code restructuring
Benefits: stable AMIP + integrated land (we believe this is the last roadblock) --> would close O10.3
Risks: what if this isn't the last roadblock....

People and Personnel

• Lead: @juliasloan25
• Collaborators: @kmdeck @szy21 @ph-kev
• Reviewers: @juliasloan25 @kmdeck @szy21 @ph-kev

Components

Restructure coupler step

Current order of step!:

• step all models (order agnostic)
• update area fractions of surface models
• exchange (import from each component into the coupler fields, then send relevant info to components, e.g. surface temp for radiation calc.)
• compute turbulent fluxes and update each component model
• call callbacks, save diagnostics, check conservation if enabled

New order of step! after this proposed change:

• step surface models (note this introduces an ordering; atmosphere must be stepped later)
  • in the integrated land step, turbulent fluxes will be computed as the model state is solved for
• weight turbulent fluxes from each surface model and pass them to the atmosphere (note this uses the area fractions from the previous step for all surfaces, which should be ok)
• step atmosphere model
• update area fractions of surface models
• exchange
• compute turbulent fluxes (for all surfaces except integrated land) and update each surface model (but not the atmosphere)
• call callbacks, save diagnostics, check conservation if enabled

Compute fluxes in land step for coupled runs

Right now, we have a method of ClimaCoupler.FluxCalculator.compute_surface_fluxes! defined for the integrated land simulation, and this is called by the coupler to compute fluxes over the land. Instead, we want the land to compute fluxes as part of its step when it's run with either a prescribed or coupled atmosphere.

Concrete changes:

• ClimaCoupler.FluxCalculator.compute_surface_fluxes! for integrated land should do nothing
• ClimaLand: rename coupler_compute_turbulent_fluxes! -> turbulent_fluxes!, so this method is called when we run with a CoupledAtmosphere

Additional ideas

• add a new type to distinguish which surfaces are implicit - ImplicitSurfaceModel ? (generally, make sure this solution is extensible to sea ice if we expect it will help with that)
• make sure we still handle initial component model exchange correctly and maintain reproducible restarts

Inputs

• Existing coupler setup
• ClimaLand flux calculation functions

Results and Deliverables

• Unchanged results for coupled simulations not using integrated land
• AMIP + integrated land with stability comparable to AMIP + bucket

Scope of Work (Tasks)

• ClimaLand: rename coupler_compute_turbulent_fluxes! -> turbulent_fluxes!, so this method is called when we run with a CoupledAtmosphere (test on a branch first) compute fluxes when using CoupledAtmosphere ClimaLand.jl#1538
• Separate step of surface models and atmosphere
• Separate flux calculation from update of fluxes in atmosphere
• In turbulent_fluxes!, compute fluxes for each surface except integrated land (this is where we may want a new type e.g. ImplicitSurfaceModel)
• FluxCalculator.compute_surface_fluxes! for the integrated land should now just access the precomputed fluxes for each land component, remap them onto the boundary space, combine them based on snow cover fraction, and update the coupler fields
• Verify no changes in AMIP + bucket, slabplanet + bucket
• Run AMIP + integrated land for long enough to test stability (TODO determine setup and run length)

SDI Revision Log

SDI opened 7 Nov 2025 by @juliasloan25

CC

@tapios @cmbengue