2.4. Configuring and running a case (CESM/NorESM)

Note

This page describes the CESM/NorESM workflow, which uses the CIME case-control system. It covers only the parts that affect the CMEPS mediator; for the general CIME workflow (create_newcase, case.setup, case.build, case.submit) refer to the CIME project at https://github.com/ESMCI/cime. The UFS workflow is covered separately in Configuring and running a case (UFS).

From a CMEPS point of view, two kinds of configuration matter: the coupling intervals (which shape the run sequence) and the mediator attributes and namelist settings (which reach the mediator through the run configuration). Both are set in the case directory — some through xml variables changed with xmlchange, others through the driver namelist file user_nl_cpl.

2.4.1. Where settings live: xml versus user_nl_cpl

CESM/NorESM configuration is split between two mechanisms, and it matters which one a given setting uses:

  • xml variables, changed with ./xmlchange VAR=value. These control case-level structure — components, processor layout, coupling intervals, run length — and are used to generate the run sequence and parts of the run configuration.

  • the driver namelist, edited in user_nl_cpl. These set individual mediator namelist values in drv_in (and in turn the attributes CMEPS reads). Some driver values are defined by xml variables and must be changed with xmlchange instead of user_nl_cpl — user_nl_cpl itself documents which.

2.4.2. Setting the coupling intervals

Coupling intervals are set per component with the <COMP>_NCPL xml variables, relative to a base period:

  • NCPL_BASE_PERIOD — the base period the couplings are counted against (for example one day).

  • ATM_NCPL, OCN_NCPL, ICE_NCPL, LND_NCPL, ROF_NCPL, GLC_NCPL, WAV_NCPL — the number of times each component is coupled per base period.

A component’s coupling interval is NCPL_BASE_PERIOD / <COMP>_NCPL. For example, with a base period of one day, ATM_NCPL=48 gives a 30-minute atmosphere coupling interval and OCN_NCPL=24 gives a one-hour ocean coupling interval:

./xmlchange NCPL_BASE_PERIOD=day
./xmlchange ATM_NCPL=48
./xmlchange OCN_NCPL=24

These intervals are exactly what determine the nesting of the @<dt> time loops in the generated run sequence — the faster-coupled components end up in the inner loops. See The run sequence for how to read the result.

2.4.3. Controlling the mediator through user_nl_cpl

Mediator behavior is adjusted by adding driver namelist settings to user_nl_cpl. The most commonly used groups are:

  • Water and energy budgets — do_budgets turns the budget diagnostics on, and the budget_* settings (budget_inst, budget_daily, budget_month, budget_ann, budget_ltann, budget_ltend, …) select which averaging periods are printed.

  • Atmosphere/ocean fluxes — aoflux_grid selects the grid on which the mediator computes air-sea fluxes.

  • History and auxiliary history — the history_option_* / history_n_* settings control mediator history output, and the histaux_* settings configure auxiliary history streams (for example histaux_atm2med_*).

  • Debugging — dbug_flag sets the mediator’s diagnostic verbosity and check_for_nans enables NaN checking on coupled fields.

  • Special couplings — for example ocn2glc_coupling and wav_coupling_to_cice enable particular exchanges when the relevant components are active.

Note

coupling_mode — which selects the host exchange logic — is normally set by the compset rather than changed by hand. See NUOPC attributes (CESM/NorESM).

2.4.4. How it fits together

Putting the pieces together for a CESM/NorESM case:

  1. xmlchange sets the components, coupling intervals and run length.

  2. CIME generates the run sequence from those intervals and writes the run configuration (nuopc.runconfig), folding in the driver and mediator attributes — including any values you set in user_nl_cpl.

  3. At run time the driver ingests the run configuration and run sequence, and the mediator obtains the attributes it needs and executes the MED phases in the order the run sequence specifies.

For the details of the two files the driver ingests, see The run sequence and NUOPC attributes (CESM/NorESM).

2.4.5. Branch runs and the coupler restart pointer

A branch run continues exactly from another case’s restarts, so the mediator reads its coupler restart. In addition to the usual branch settings, you must set the coupler restart pointer explicitly to the dated rpointer.cpl file of the reference case:

./xmlchange RUN_STARTDATE=1990-01-01
./xmlchange RUN_REFDATE=1990-01-01
./xmlchange DRV_RESTART_POINTER=rpointer.cpl.1990-01-01-00000

The coupler restart pointer files are dated — for example rpointer.cpl.1850-01-06-00000 for a restart written at that timestamp. Setting DRV_RESTART_POINTER explicitly for a branch run is by design:

  • On a continue run (CONTINUE_RUN=TRUE), CIME already knows the exact restart it just wrote and automatically sets DRV_RESTART_POINTER to that dated pointer, so you never touch it.

  • On a branch run, you are instead choosing which restart of a reference case to resume from — information CIME does not have on its own (RUN_REFDATE gives the date, but the reference case may hold several restart snapshots). So you name the pointer yourself, consistent with the RUN_REFCASE / RUN_REFDATE you already set.

Note

A hybrid run does not read the coupler restart at all, so the pointer does not apply there.