NUOPC driver

We have adopted the NUOPC driver from CESM.

Component initialisation

Model component initialisation strategy is specified through a combination of flags set in the nuopc.runconfig configuration file and the input parameter files for each component.

The start_type parameter in the ALLCOMP_attributes section of nuopc.runconfig can be set to one of three values (note that the access-om3 Payu driver automatically sets this parameter depending on whether the run is an initial or restart run):

"startup" specifying an initial run,
"continue" specifying a run starting from restart files,
"branch" specifying a run starting from restart files in which properties of the output history files may be changed - not used here.

These have the following effects on each ACCESS-OM3 component’s parameters settings:

MOM6

See MOM6 NUOPC cap for details.

`start_type`	Interaction with model parameters (from `input.nml`)
`"startup"`	Sets parameter `restartfiles = "n"`.
`"continue"` / `"branch"`	Hardcoded to use restart file specified in a local file `rpointer.ocn`.

Note, users should let NUOPC set the restartfiles parameter. It should not be specified in input.nml.

CICE6

See CICE6 NUOPC cap for details.

`start_type`	Interaction with model parameters (from `ice_in`)
`"startup"`	Sets parameter `runtype = "initial"`. The type of CICE startup can be further configured using the `ice_ic` parameter in `ice_in` - see here.
`"continue"` / `"branch"`	Sets parameters `restart = .true.` , `runtype = "continue"` and `use_restart_time = .true.` so uses restart specified in file specified in parameter `pointer_file`.

Note, users should let NUOPC set the restart, runtype and use_restart_time parameters. They should not be specified in ice_in.

CDEPS components (DATM, DROF)

See e.g. the atm NUOPC cap and patch, and here for details.

`start_type`	Interaction with model parameters (from `d{model_name}_in`)
`"startup"`	Does not attempt to read any restarts regardless of parameter values.
`"continue"` / `"branch"`	If parameter `skip_restart_read = .false.`, then reads restart specified in file `rpointer.{model_name}` or reads restart specified in parameter `restfilm` if it isn't set to `"null"` - see here.

Note, restarts are used for the CDEPS components in ACCESS-OM3 only for performance reasons. They’re not needed to restart exactly, but they reduce startup cost associated with reading the input dataset time axis information - see here for more detail.

Time-steps

Also see timestepping section here.

Coupling and driver time-step

There's an overview of the NUOPC timekeeping design here.

The nuopc.runseq file specifies the run sequence of the configuration. The run sequence for current ACCESS-OM3 configurations comprises a single loop, with the coupling time-step specified at the start of the loop (this is the “timeStep” of the loop in NUOPC-speak).

Note, that there are parameters {model_name}_cpl_dt set in the CLOCK_attributes section of nuopc.runconfig. The only place these are used in CMEPS is to set the driver time-step as the minimum of these values. However from the NUOPC documentation and CMEPS codebase:

Each time loop has its own associated clock object. NUOPC manages these clock objects, i.e. their creation and destruction, as well as startTime, endTime, timeStep adjustments during the execution. The outer most time loop of the run sequence is a special case. It uses the driver clock itself. If a single outer most loop is defined in the run sequence provided by freeFormat, this loop becomes the driver loop level directly. Therefore, setting the timeStep or runDuration for the outer most time loop results modifying the driver clock itself. However, for cases with concatenated loops on the upper level of the run sequence in freeFormat, a single outer loop is added automatically during ingestion, and the driver clock is used for this loop instead.

So I think in our case, {model_name}_cpl_dt are unused and the driver time-step equals the coupling time-step set in nuopc.runseq. Certainly, changing these values seems to have no effect. However, I would feel more comfortable if I understood why {model_name}_cpl_dt are ever needed...

CICE6 time-steps

The CICE thermodynamics time-step (dt; seconds) is set in the CICE NUOPC cap to match the driver time-step, which equals the coupling time-step. Setting dt in ice_in has no impact and can only be changed by changing the coupling timestep. Other time-step related parameters (ndtd and ndte) can be set in ice_in. Setting ndtd within ice_in allows for sub-cycling of the sea-ice dynamics to ensure numerical stability and may need to be increased during initial model spin up (the thermodynamics should be numerically stable for any time-step).

MOM6 time-steps

MOM6 has 5 timesteps - see these references:

From shortest to longest they are: barotropic (DTBT), baroclinic Lagrangian (DT), tracer advection (DT_TRACER_ADVECT), thermodynamic (DT_THERM) and vertical remapping. Note that currently in MOM6 remapping is performed as part of the thermodynamic step so their timesteps cannot be set independently. It is common to set at least these 3 timesteps in the MOM_input file:

Barotropic time-step (DTBT) for integration of sea surface and depth-averaged horizontal velocity. If set negative (e.g. DTBT = -0.95), the magnitude of DTBT is interpreted a fraction of the stability limit, so can be set independently of the model configuration (e.g. resolution). DTBT_RESET_PERIOD controls how often the stability limit is recalculated.
Baroclinic time-step (DT) for Lagrangian stacked shallow-water equations; often called "the" model timestep; needs to be short enough to resolve internal gravity waves, inertial oscillations and advection on the horizontal grid (i.e. this is resolution-dependent).
Thermodynamics time-step (DT_THERM), which can be set to resolve the relevant physics (e.g. one to three hours or so to capture the diurnal cycle), independent of the horizontal grid resolution. It is possible to set DT_THERM longer than the coupling time-step, but only with DIABATIC_FIRST = False. The tracer advection timestep (DT_TRACER_ADVECT) defaults to the same as DT_THERM.