The lag concept

If no lag index or if a lag index equal to 0 is given by the user in the namcouple for a particular coupling field, the sending or receiving actions will actually be performed, below the prism_put_proto called in the source model or below the prism_get_proto called in the target model respectively, each time the date argument on both sides matches an integer number of coupling periods.

To match a prism_put_proto called by the source model at a particular date with a prism_get_proto called by the target model at a different date, the user has to define in the namcouple an appropriate lag index, LAG, for the coupling field(see section 5). The value of the LAG index must be expressed in ``number of seconds''; its value is automatically added to the prism_put_proto date value and the sending action is effectively performed when the sum of the date and the lag matches an integer number of coupling periods. This sending action is automatically matched, on the target side, with the receiving action performed when the prism_get_proto date argument equals the same integer number of coupling periods.

Note that when there is a lag, the first instance of the source field is missing in the debug file (EXPOUT or IGNOUT fields, see section 5.3) because the first source field is not sent by the source model with a prism_put_proto but directly read by OASIS3 from a coupling restart file.

1. LAG concept first example

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

   On the 4 figures in this section, short black arrows correspond to prism_put_proto or
   prism_get_proto called in the component model that do not lead to any sending or receiving action; long black arrows correspond to prism_put_proto or prism_get_proto called in the component models that do effectively lead to a sending or receiving action; long red arrows correspond to prism_put_proto or prism_get_proto called in the component models that lead to a reading or writing of the coupling field from or to a coupling restart file (either directly or through OASIS3 main process).

   Figure 4.4: 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$ sending action by model A/B was used at a coupling timestep to match the model B/A receiving action, a deadlock would occur as both models would be initially waiting on a receiving 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 receiving 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 prism_put_proto performed at time 8 and 20 by model A will then lead to sending actions (as 8 + 4 = 12 and 20 + 4 = 24 which are coupling periods) that match the receiving actions performed at times 12 and 24 below the prism_get_proto called by model B. For $F_2$, the prism_put_proto performed at time 18 by model B then leads to a sending action (as 18 + 6 = 24 which is a coupling period) that matches the receiving action performed at time 24 below the prism_get_proto called by model A.

   At the beginning of the run, as their LAG index is greater than 0, the first prism_get_proto of $F_1$ and $F_2$ will automatically be fulfilled by OASIS3 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$ prism_put_proto as the date + $F_1$ lag equals a coupling time. The analogue is true for $F_2$. These values will automatically be read in at the beginning of the next run below the respective prism_get_proto.

2. LAG concept second example

   A second coupling algorithm exploiting the LAG concept is illustrated on figure 4.5. 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 4.5: LAG concept second example

   

   For $F_1$ and $F_2$ the situation is similar to the first example. If $F_1$/$F_2$ sending action by model A/B was used at a coupling timestep to match the model B/A receiving action, a deadlock would occur as both models would be waiting on a receiving 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 receiving actions, which means that a lag of 6 must be defined for both $F_1$ and $F_2$. For both coupling fields, the prism_put_proto performed at times 6 and 18 by the source model then lead to sending actions (as 6 + 6 = 12 and 18 + 6 = 24 which are coupling periods) that match the receiving action performed at time 12 and 24 below the prism_get_proto 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 prism_get_proto performed at the beginning of the run for $F_1$ and $F_2$, automatically read them from their coupling restart files, and the last prism_put_proto performed at the end of the run automatically write them to their coupling restart file. For $F_3$, no coupling restart file is needed nor used as at each coupling period the coupling field produced by model A can be directly ``consumed'' by model B.

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