...
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
...
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.
...
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.
...