...
Driver/Coupler Code pointers
There have been versions of the coupler in the E3SM parent model, CESM. The most recent is called "cpl7" and is written using MCT datatypes and methods.
The MCT-based version of cpl7 is in https://github.com/E3SM-ProjectESMCI/E3SMcime/tree/master/cime/src/drivers/mct/main
To use the cpl7, each component must instantiate cpl7 datatypes and use cpl7 methods to communicate with the coupler/driver (these are mostly wrappers around MCT datatypes and methods). The datatypes store all transferred data in memory.
Example: EAM's code to do this is located in https://github.com/E3SM-Project/E3SM/blob/master/components/cameam/src/cpl/atm_comp_mct.F90
At a runtime-selectable frequency, each component will communicate with the coupler, sending data it has calculated. At the same frequency, but at possibly a different place in the component's call sequence, it will receive data from the coupler
...
("prep" stands for "prepare" and those routines ensure all the data needed for the component is ready for next time it's its 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 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 calls 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 it has received from the previous iteration.
...
How often each component sends/receives data to/from the coupler is first determined by the NCPL_BASE_PERIOD. This is almost always 1 day and is set in env_run.xml.
The coupler communication frequency is expressed as an integer number of times per NCPL_BASE_PERIOD. The atmosphere's coupling frequency is denoted by NCPL_ATM in the xml config files. The frequency depends on the component set and the grid and the options are in the driver's config_component.xml seen in https://github.com/E3SM-Project/E3SM/blob/maint-1.0/cime/src/drivers/mct/cime_config/config_component_e3sm.xml
In a fully coupled case with 1-degree resolution in the atmosphere, the NCPL_ATM =48. With a base period of 1 day, the atmosphere communicates with the coupler very every 30 simulated minutes. The longest time step for the atmosphere (dtime) is also set to 30 minutes. (The "dtime" variable in the atmosphere namelist is ignored). The atmosphere may (and often does) subcycle parts of its solve within that 30 minutes.
...
The driver contains code for time-averaging the data to be sent to a component if the coupler frequencies don't match. For example if NCPL_OCN is set to 3 hours while the NCPL_ATM is 1 hour, the coupler will accumulate the atmosphere ocean fluxes calculated every time the atmosphere talks to the coupler and send sends the ocean the average.
In the current implementation, the coupling period must be identical for the atmosphere, sea ice, and land components. The ocean coupling period can be the same or greater. The runoff coupling period should be between or the same as the land and ocean coupling period. All coupling periods must be multiple integers of the smallest coupling period and will evenly divide the NCPL_BASE_PERIOD. No component model can have a time-step longer then its coupling period.
Flux calculation
The atmosphere-ocean fluxes are unique in being calculated in the coupler. This was done because for a long time the ocean only talked to the coupler once a day but the atmosphere needed fluxes that changed with the changing lower-atmosphere-level properties. Also the fluxes are calculated on the high-resolution (ocean) grid. So in the coupler, SST was held fixed and new heat and momentum fluxes would be calculated as new atmosphere properties were sent to the coupler (and interpolated to the ocean grid). The fluxes are interpolated back to the atmosphere grid and sent to the atmosphere. Meanwhile, the fluxes (on the ocean grid) are summed and then averaged before sending to the ocean.
...
The fields that are exchanged between components and the coupler are hard-coded in text strings in a file called seq_flds_mod.F90 (see https://github.com/E3SM-ProjectESMCI/E3SMcime/blob/master/cime/src/drivers/mct/shr/seq_flds_mod.F90).
The colon-separated strings are parsed by MCT to figure out how much space to allocate in its datatypes to hold the data (by counting substrings between colons) and the substrings are used to find specific values with an MCT "Attribute Vector".
...
When sending to or receiving form from the coupler, a component must do a deep copy between its internal data type and the cpl7 datatype (the MCT attribute vector). In the atmosphere, you can see this copy in/out done in https://github.com/E3SM-Project/E3SM/blob/master/components/cameam/src/cpl/atm_import_export.F90. Here are a few lines from the code that copies data in to cpl7 data types for sending to the coupler.
...
Once data has been copied in to the cpl7 data types, the coupler can perform all necessary interpolation and data transfer to get the data to the components that need it. The sending component, in this case the atmosphere, needs to send the union of all requested data but doesn't have to know where it all it goes. Similarly, the coupler expects to receive good values for all this data but doesn't need to know if from a "real" model or from a "data model" that is reading it from files.
...