Sending a coupling (or I/O) field

In the component time step loop, each process sends its part of the coupling (or I/O) field.

• CALL oasis_put (var_id, date, fld1, info, fld2, fld3, fld4, fld5)
• CALL prism_put_proto(var_id, date, fld1, info, fld2, fld3, fld4, fld5)
  • var_id [INTEGER; IN]: field ID (returned from corresponding oasis_def_var, see section 2.2.5)
  • date [INTEGER; IN]: number of seconds (or any other time units as long as the same are used in all components and in the namcouple) at the time of the call (by convention at the beginning of the timestep)
  • fld1 [REAL, IN]: coupling (or I/O) field array; can be 1D or 2D
  • info [INTEGER; OUT]: returned info code:
    • OASIS_Sent(=4) if the field was sent to another component
    • OASIS_LocTrans (=5) if the field was only used in a time transformation (not sent, not output)
    • OASIS_ToRest (=6) if the field was written to a restart file only
    • OASIS_Output (=7) if the field was written to an output file only
    • OASIS_SentOut (=8) if the field was both written to an output file and sent to another component (directly or via OASIS3 main process)
    • OASIS_ToRestOut (=9) if the field was written both to a restart file and to an output file.
    • OASIS_WaitGroup (=14) if the field was not sent because it is part of a group. It will be sent only when the oasis_put of the last field in the group will be called.
    • OASIS_Ok (=0) otherwise and no error occurred.
  • fld2 [REAL, IN, OPTIONAL]: optional $2^{nd}$ coupling field array; can be 1D or 2D
  • fld3 [REAL, IN, OPTIONAL]: optional $3^{rd}$ coupling field array; can be 1D or 2D
  • fld4 [REAL, IN, OPTIONAL]: optional $4^{th}$ coupling field array; can be 1D or 2D
  • fld5 [REAL, IN, OPTIONAL]: optional $5^{th}$ coupling field array; can be 1D or 2D

To ensure a proper use of the oasis_put, one has to take care of the following aspects:

• A $2^{nd}$, $3^{rd}$, $4^{th}$ and $5^{th}$ source field can be passed as optional arguments. If so, the $2^{nd}$, $3^{rd}$, $4^{th}$ and $5^{th}$ set of weights present in the remapping file will be applied, respectively (see section 5.4 for the weight file format). This will be used for example for the SCRIPR/BICUBIC remapping for which a $1^{st}$, $2^{nd}$, $3^{rd}$, $4^{th}$ set of weights should be respectively applied to the field value, its gradient in the first dimension, its gradient in the second dimension, and its cross-gradient. Bicubic and higher order remapping are therefore supported given that the higher order fields are provided at each time step as oasis_put arguments. Note that if fld3, or fld4, or fld5 are passed, fld2, or fld3 and fld2, or fld4 and fld3 and fld2 must also be passed respectively. However, having a $2^{nd}$, $3^{rd}$, $4^{th}$ and $5^{th}$ set of weights in the remapping file but not passing a $2^{nd}$, $3^{rd}$, $4^{th}$ and $5^{th}$ source field as argument will not lead to an error.

• This routine may be called by the component at each timestep. The convention for the date argument is to indicate the time at the beginning of the timestep. The sending is actually performed if the time obtained by adding the field lag (LAG in the namcouple, if any, with LAG=0 by default) to the date corresponds to a time at which it should be activated, given the coupling or I/O period indicated by the user in the namcouple (see section 3).

• By convention, the first coupling of a run occurs at date=0 and the final coupling occurs at date = runtime-cpl_period, where runtime is the total time of the run and cpl_period is the coupling period of the field indicated by the user in the namcouple (see section 3).

• For a coupling field with a positive lag, the coupling restart file (see section 5.2) is automatically overwritten by the oasis_put when the date+LAG=runtime.

• The total run time should match an integer number of coupling periods.

• If a local time transformation is indicated for the field by the user in the namcouple (INSTANT, AVERAGE, ACCUMUL, T_MIN or T_MAX, see section 4), it is automatically performed and the resulting field is finally sent at the coupling or I/O frequency. For non-instant transformations, partially transformed fields will be written to the restart file at the end of the run for use on the next component startup, when needed.

• A coupling field sent by a source component can be associated with more than one target field and component, if specified as so with different entries in the namcouple configuration file. In that case, the source component needs to send the field only once and the corresponding data will arrive at multiple targets as specified in the namcouple. Different coupling frequencies and transformations are allowed for different coupling exchanges of the same field. If coupling restart files are required (either if a LAG or if a LOCTRANS transformation is specified), it is mandatory to specify different files for the different fields.

• Trying to send with oasis_put a field declared with a oasis_def_var but not defined in the configuration file namcouple will lead to an abort. In this case, the field ID returned by the oasis_def_var is equal to -1 and the corresponding oasis_put should not be called.