The CoupledSimulation Object

CoupledSimulation is the central object in ClimaCoupler.jl. It holds everything needed to run a coupled simulation: the component models, exchange fields, time-stepping information, output directories, diagnostics, and callbacks. It is created by the CoupledSimulation constructor and passed to run!, step!, or postprocess.

Here we will describe the structure and internals of CoupledSimulation.

CoupledSimulation Fields

Component model simulations (cs.model_sims)

cs.model_sims is a NamedTuple containing one entry per active component model. Only models that are present in the simulation appear in the tuple — for example, an aquaplanet simulation has no land_sim or ice_sim. The standard keys are:

Each value is a concrete subtype of AbstractComponentSimulation. You can iterate over all component models with:

for sim in cs.model_sims
    @info nameof(sim), extrema(Interfacer.get_field(sim, Val(:surface_temperature)))
end

See Available Simulation Types for details on which models are present in each simulation type.

Coupler exchange fields (cs.fields)

cs.fields is a ClimaCore.Fields.Field of NamedTuples defined on the shared boundary (exchange) grid. It holds the intermediate values passed between the atmosphere and surface models at each coupling step. Individual fields are accessed as properties:

cs.fields.T_sfc        # combined surface temperature on the exchange grid
cs.fields.F_lh         # latent heat flux
extrema(cs.fields.SW_d)  # check shortwave radiation range

The full list of default fields and their descriptions is documented in Interfacer. Component models can register additional fields beyond the defaults by extending Interfacer.add_coupler_fields!. The full list of exchange fields of a simulation can be inspected with propertynames(cs.fields).

Output directories (cs.dir_paths)

cs.dir_paths is a NamedTuple of directory paths set up at initialization, with the following structure and keys in the NamedTuple:

output_dir_root/           → `output_dir_root`
├── clima_coupler/         → `coupler_output_dir`
├── clima_atmos/           → `atmos_output_dir`
├── clima_land/            → `land_output_dir`
├── clima_ocean/           → `ocean_output_dir`
├── clima_seaice/          → `ice_output_dir`
├── artifacts/             → `artifacts_dir`
├── checkpoints/           → `checkpoints_dir`
└── regrid_tmp_<random>/   → `regrid_dir`

See Utilities.setup_output_dirs for how these directories are created and how to customise the root path via the coupler_output_dir configuration option.

Callbacks (cs.callbacks)

cs.callbacks is a NamedTuple of TimeManager.Callback objects, which each execute some operation at predetermined times throughout a simulation. Each callback wraps a schedule and a function, and is triggered at the appropriate time during step!. The default callbacks include a walltime progress reporter and, if enabled, a checkpointing callback. See TimeManager for the Callback API and Checkpointer for how to add a checkpointing callback.

Conservation checks (cs.conservation_checks)

When energy and water conservation checking is enabled (via the energy_check configuration option), cs.conservation_checks is a NamedTuple with keys :energy and :water, holding an EnergyConservationCheck and a WaterConservationCheck respectively. Otherwise it is nothing. Conservation checks are only supported for slabplanet simulations. See ConservationChecker for details.

Diagnostics handler (cs.diags_handler)

cs.diags_handler is a ClimaDiagnostics.DiagnosticsHandler that schedules and writes diagnostic output variables throughout the simulation. It is nothing when use_coupler_diagnostics is disabled. See Diagnostics Setup for how to configure which variables are saved and at what frequency.

Thermodynamic parameters (cs.thermo_params)

cs.thermo_params is a Thermodynamics.Parameters.ThermodynamicsParameters object shared across all component models. It is used by FluxCalculator when computing turbulent surface fluxes. In testing contexts only it may be nothing.

Turbulent flux accumulators (cs.flux_accumulators)

cs.flux_accumulators is a NamedTuple of FluxCalculator.FluxAccumulator objects, keyed by the surface simulation name (e.g. :ocean_sim, :ice_sim). Each accumulator holds a step counter as well as the running sum of each turbulent flux (F_lh, F_sh, F_turb_moisture, F_turb_ρτxz, F_turb_ρτyz) for this simulation, defined on the coupler boundary space.

An entry is allocated only for "slow explicit" surfaces — surfaces whose own timestep is larger than Δt_cpl, that are not AbstractImplicitFluxSimulation (integrated land), and that are not AbstractSurfaceStub (prescribed data without turbulent flux exchange). All other surfaces have no entry in this NamedTuple, and the coupler pushes turbulent fluxes directly via FluxCalculator.update_turbulent_fluxes! at every coupling step.

When an accumulator is present, the coupler:

• adds the per-surface turbulent flux to the accumulator each coupling step (instead of calling update_turbulent_fluxes! on that surface), and
• if the surface is about to step, divides the accumulator by n_steps, writes the time-averaged flux to the surface boundary conditions via update_turbulent_fluxes!, and resets the accumulator.

The area-weighted combined csf.F_* fields (which the atmosphere reads) are recomputed every call to turbulent_fluxes! regardless of accumulator state. See FluxCalculator for the accumulator API.

Checkpoint settings (cs.save_cache, cs.prev_checkpoint_t)

cs.save_cache controls whether model caches (in addition to states) are written when a checkpoint is saved. Setting this to false produces smaller checkpoint files but prevents exact cache restoration on restart. cs.prev_checkpoint_t is a Ref tracking the simulation time of the last checkpoint, used internally to remove intermediate checkpoint files. See Checkpointer for the full checkpointing documentation.