3 The lag concept

Using the OASIS3-MCT coupling library, the user has the flexibility to reproduce different coupling algorithms defining LAG values for the different coupling fields . In the components, the sending and receiving routines, respectively oasis_put and oasis_get, can be called at each component timestep, with the appropriate date argument giving the actual time (at the beginning of the timestep), expressed in number of seconds since the start of the run, or in any other time units as long as the same are used in all components and in the namcouple (see section 2.2.7). This date argument is automatically analysed by the coupling library and depending on the coupling period and the lag chosen by the user for the coupling field in the namcouple (LAG), different coupling algorithms can be reproduced without modifying the component codes themselves.

The lag (LAG) must be expressed in the time unit used (that must be the same in the components and in the namcouple, see section 2.2.7) and can be positive or negative but should never be larger (in absolute magnitude) than the coupling period of any field due to problems with restartability and dead-locking. When a component calls a oasis_put, the value of the lag is automatically added to the value of the date argument and the “put” is actually performed when the sum date+lag is a coupling time; in the target component, this “put” will match a oasis_get for which the date argument is the same coupling time. So the lag only shifts the time at which the data is sent but not the time at which the data is received.

When the lag is positive, a restart file must be available to initiate the coupling. For a field with positive lag, the source component automatically reads the field in the restart file during the coupling initialization phase (below the oasis_enddef) and send the data to match the oasis_get performed at time=0 in the target component. The final coupling data on the source side will then be automatically written to the restart file for use in the next run⁷.

On the 4 figures in this section, short black arrows correspond to oasis_put or oasis_get called in the component that do not lead to any “put" or receiving action; long black arrows correspond to oasis_put or oasis_get called in the components that do actually lead to a “put" or “get” action; long red arrows correspond to oasis_put or oasis_get called in the component models that lead to a reading or writing of the coupling field from or to a coupling restart file.

1. LAG concept first example

   A first coupling algorithm, exploiting the LAG concept, is illustrated on figure 2.9.

   Figure 2.9: LAG concept first example

   

   During a coupling timestep, model A receives $F_2$ and then sends $F_1$; its timestep length is 4. During a coupling timestep, model B receives $F_1$ and then sends $F_2$; its timestep length is 6. $F_1$ and $F_2$ coupling periods are respectively 12 and 24. If $F_1$/$F_2$ “put" action by model A/B was used at a coupling timestep to match the model B/A “get" action, a deadlock would occur as both models would be initially waiting on a “get" action. To prevent this, $F_1$ and $F_2$ produced at the timestep before have to be used to match respectively the model B and model A “get" actions.

   This implies that a lag of respectively 4 and 6 seconds must be defined for $F_1$ and $F_2$. For $F_1$, the oasis_put performed at time 8 and 20 by model A will then lead to “put" actions (as 8 + 4 = 12 and 20 + 4 = 24 which are coupling periods) that match the “get" actions performed by oasis_get called by model B at times 12 and 24. For $F_2$, the oasis_put performed at time 18 by model B then leads to a “put" action (as 18 + 6 = 24 which is a coupling period) that matches the “get" action performed at time 24 by the oasis_get called by model A.

   At the beginning of the run, as their LAG index is greater than 0, the first oasis_get of $F_1$ and $F_2$ will automatically be fulfilled with fields read from their respective coupling restart files. The user therefore has to create those coupling restart files before the first run in the experiment. At the end of the run, $F_1$ having a lag greater than 0, is automatically written to its coupling restart file below the last $F_1$ oasis_put as the date+lag equals the total run time. The analogue is true for $F_2$. These coupling restart fields will automatically be read in at the beginning of the next run below the respective oasis_get.

2. LAG concept second example

   A second coupling algorithm exploiting the LAG concept is illustrated on figure 2.10. During its timestep, model A receives $F_2$, sends $F_3$ and then $F_1$; its timestep length is 6. During its timestep, model B receives $F_1$, receives $F_3$ and then sends $F_2$; its timestep length is also 6. $F_1$, $F_2$ and $F_3$ coupling periods are both supposed to be equal to 12.

   Figure 2.10: LAG concept second example

   

   For $F_1$ and $F_2$ the situation is similar to the first example. Without any lag specified and without any restart file, a deadlock would occur as both models would be waiting on a “get" action. To prevent this, $F_1$ and $F_2$ produced at the timestep before have to be used to match the model A and model B “get" actions, which means that a lag of 6 must be defined for both $F_1$ and $F_2$. For both coupling fields, the oasis_put performed at times 6 and 18 by the source model then lead to “put" actions (as 6 + 6 = 12 and 18 + 6 = 24 which are coupling periods) that match the “get" action performed at time 12 and 24 by the oasis_get called by the target model.

   For $F_3$, sent by model A and received by model B, no lag needs to be defined: the coupling field produced by model A at the coupling timestep can be “consumed” by model B without causing a deadlock situation.

   As in the first example, the oasis_get performed at the beginning of the run for $F_1$ and $F_2$, will automatically receive data read from their coupling restart files, and the last oasis_put performed at the end of the run automatically write them to their coupling restart file. For $F_3$, no coupling restart file is needed.

   We see here how the introduction of appropriate LAG indices results in receiving in the target component the coupling fields produced by the source component the time step before; this is, in some coupling configurations, essential to avoid deadlock situations.

Footnotes

... run⁷

When there is a lag, the first and last instance of the source field in the debug netCDF file (EXPOUT fields, see section 3.3) always correspond respectively to the field read from and written to the restart file.