1 Sending a coupling (or I/O) field or writing a coupling restart file

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,write_restart)
• CALL prism_put_proto(var_id, date, fld1, info, fld2, fld3, fld4, fld5, write_restart)
  • 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, 2D, bundle 1D, or bundle 2D, see above.
  • 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
    • 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; however, the field is buffered and therefore the field array can be modified in the component code when returning from the oasis_put call.
    • OASIS_Ok (=0) otherwise and no error occurred.
  • fld2 [REAL, IN, OPTIONAL]: optional $2^{nd}$ coupling field array; can be 1D, 2D, bundle 1D, or bundle 2D. Rank and size must match fld1.
  • fld3 [REAL, IN, OPTIONAL]: optional $3^{rd}$ coupling field array; can be 1D, 2D, bundle 1D, or bundle 2D. Rank and size must match fld1.
  • fld4 [REAL, IN, OPTIONAL]: optional $4^{th}$ coupling field array; can be 1D, 2D, bundle 1D, or bundle 2D. Rank and size must match fld1.
  • fld5 [REAL, IN, OPTIONAL]: optional $5^{th}$ coupling field array; can be 1D, 2D, bundle 1D, or bundle 2D. Rank and size must match fld1.
  • write_restart [LOGICAL, IN, OPTIONAL]: optional argument to write an intermediate restart file associated with the variable var_id at the current timestep (see below).

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 remapping 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 in that order. For SCRIPR/BICUBIC, fld2, fld3 and fld4 are therefore mandatory.

  This will be used also for the CONSERV/SECOND for which a 1st, 2nd, 3rd set of weights should be respectively applied to the field value, its gradient with respect to the latitude ($\theta$) $\frac{\delta f}{\delta \theta}$ and its gradient with respect to the longitude ($\phi$) $\frac{1}{cos \theta}\frac{\delta f}{\delta \phi}$ in that order. For CONSERV/SECOND, fld2 and fld3 are therefore mandatory.

  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.

• Note that from OASIS3-MCT_4.0 onwards, the number of weights in the remapping file and the number of fields in the coupling restart file (when such a file is needed) must strictly match the number of source fields passed to the oasis_put .

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

• 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-instantaneous 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, 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. When a field is not defined in the namcouple, the field ID returned by the oasis_def_var is equal to -1 and the corresponding oasis_put should not be called.

• Coupling multiple fields via a single communication is supported through colon delimited field lists in the namcouple (see 3.3.1). All fields will use the namcouple settings for that entry. In the component model codes, these fields are still sent (“put”) one at a time. Inside OASIS3-MCT, the fields are stored and a single mapping and send instruction is executed for all fields. This is useful to reduce communication costs by aggregating multiple fields into a single communication when multiple fields have the same coupling transformations.

  This option does not put any constraint on the order of the related oasis_put and oasis_get in the codes.

  As they appear in one single entry line, these fields must share the same coupling restart file but this restart file may contain other fields.

• The optional argument, write_restart, in the oasis_put routine is false by default. If a user sets that argument to true, an “intermediate” restart is written for that field only for that timestep. The write_restart saves the data that exists at the time of the call, taking into account LOCTRANS operations. In cases where multiple fields are coupled as a single operation in the model (indicated via a list of colon delimited fields in the namcouple, see 3.3.1), users are encouraged to specify the write_restart flag on ALL oasis_put calls at a given time for this set of fields. Restarts are created with a 9 digit timestamp in their filename, corresponding to the time in seconds of the oasis_put call, e.g. TA000003600_rst4.nc or TC000014400_rst4.nc. A restart file that starts with TA is a restart file associated with LOCTRANS operations; a restart file that starts with TC is a restart file associated with coupling operations. The coupling restart filename defined in the namcouple (e.g. rst4.nc) is used to generate the filename of these intermediate restart files.