Terminology:
The coupler is a component that performs operations such as interpolation, time averaging or merging.
The driver is the "main" that runs on all processors and controls the overall integration of the coupled model.
A field is a quantity involved in the coupler data flow. Surface temperature, heat flux, downward longwave radiation are all examples of fields.
In CIME, the coupler and driver are referred to as "cpl7". cpl7 uses MCT datatypes to store all data in the coupler and MCT methods to perform communication and interpolation (from pre-computed weights).
See also CIME Key Terms and Concepts
Driver/Coupler Code pointers:
The MCT-based version of cpl7 is in https://github.com/E3SM-Project/E3SM/tree/master/cime/src/drivers/mct
To use the cpl7, each component must instantiate cpl7 datatypes and use cpl7 methods to communicate with the coupler/driver.
Example: EAM's code to do this is located in https://github.com/E3SM-Project/E3SM/blob/master/components/cam/src/cpl/atm_comp_mct.F90
At a runtime-selectable frequency, each component will communicate with the coupler and send it a list of data. At the same frequency, but at possibly a different place in the component's call sequence, it will receive data from the coupler
Explicit integration sequence
with atmosphere-ocean described:
The driver calls each model's run method and the various coupler functions in a fixed sequence. The driver code allows for a few slightly-different sequences that can be selected at runtime using the CPL_SEQ_OPTION in env_run.xml. The sequence used by E3SM in coupled runs is RASM_OPTION1 and illustrated below:
The above diagram is written as if each component is running on a distinct set of MPI tasks. In most real cases, the ocean is the only component on its own tasks. The other components share a separate pool of tasks to various degrees. The exact layout is controlled by the env_mach_pes.xml file in the case directory. The driver gives each component an MPI communicator with its tasks. The driver also defines several other communicators which are the union of each pair of component's tasks with the coupler. Nearly every call in the driver is in "if (communicator)" blocks to control what is called on which set of processors. This allows the driver to run various components concurrently if the processor layout allows it.
("prep" stands for "prepare" and those routines ensure all the data needed for the component is ready for next time it's run method is called.)
Read the above diagram for atmosphere-ocean as follows: at the start, the coupler has atmosphere and ocean data from either the previous step or the initialization sequence. On the coupler tasks, the driver calculates atmosphere-ocean fluxes on the ocean grid (AtmOcn Prep). The driver then calls, on the coupler tasks, "Ocn Prep" where any additional data the ocean needs (such as ice-ocean fluxes from the sea-ice model or river runoff) are merged (using a simple weighted sum with area fractions) so that the ocean gets one combined heat, freshwater or momentum flux for each of its grid points.
The driver then calls a routine that transfers data from the coupler to the ocean (the horizontal line from "Ocn Prep" to "Ocn Run") on a communicator that is the union of coupler and ocean tasks. This blocks (on that communicator) until finished.
The driver then calls the ocean's run method. The ocean will execute some number of time steps internally using the surface forcing provided by the coupler.
When the ocean finishes, it waits for the driver to call a method that transfers all the needed ocean data back to the coupler (the horizontal line going from "Ocn Run" and pointing to the left). If the driver gets to this method before the ocean is finished, the union of coupler and ocean tasks will wait.
Meanwhile, after the driver calls the ocean's run method, it can still do things on the non-ocean tasks. It receives data from other components (land, sea-ice). When the driver calls "Atm Prep" on the coupler processors, "Atm Prep" will have all the data from other components that has been transferred to the coupler (in MCT datatypes). It will perform any interpolation necessary to put that data on the atmosphere grid. It will then merge the input from multiple surface components so each atmosphere grid point has a single value for heat, water, momentum flux. The driver will then transfer the data to the atmosphere (on the union of atmosphere-coupler processors).
The driver will then call the atmosphere run method (on the atmosphere tasks). The atmosphere executes some number of time steps. While the atmosphere is running, the driver call the routine to transfer data from the ocean to the coupler (on the union of coupler and ocean tasks). The driver will then call the routine to send data from the atmosphere to the coupler (on the union of atmosphere and coupler tasks).
At this point, we are at the bottom of the run sequence and we return to the top where the coupler has the atmosphere and ocean data is has received from the previous iteration.
Time step and coupler frequency control:
Each model can set its internal time step(s) through its namelist.