2 Receiving a coupling (or I/O) field

In the component time stepping loop, each process receives its part of the coupling field.

• CALL oasis_get (var_id, date, fld, info)
• CALL prism_get_proto(var_id, date, fld, info)
  • var_id [INTEGER; IN]: field ID (returned by the corresponding oasis_def_var)
  • 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)
  • fld [REAL, OUT]: I/O or coupling field array; can be 1D, 2D, bundle 1D, or bundle 2D.
  • info [INTEGER; OUT]: returned info code:
    • OASIS_Recvd(=3) if the field was received from another component
    • OASIS_FromRest (=10) if the field was read from a restart file only
    • OASIS_Input (=11) if the field was read from an input file only
    • OASIS_RecvOut (=12) if the field was both received from another component and written to an output file
    • OASIS_FromRestOut (=13) if the field was both read from a restart file and written to an output file
    • OASIS_Ok (=0) otherwise and no error occurred.

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

• This routine may be called by the component at each timestep. The date argument is automatically analysed and the receiving action is actually performed only if date corresponds to a time for which it should be activated, given the period indicated by the user in the namcouple. An exchange at the beginning of the run at time=0 is expected.

• Trying to receive with oasis_get 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_get should not be called.

• If a coupling field has a positive lag, the coupling field that matches the oasis_get at time=0 is automatically read in from a coupling restart file and sent to match that oasis_get under the oasis_enddef of the source model (see section 2.5.3).

• 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 received (via an oasis_get) one at a time. Inside OASIS3-MCT, the fields are stored and a single mapping and receive instruction is executed for all fields. This is useful in cases where multiple fields have the same coupling transformations and to reduce communication costs by aggregating multiple fields into a single communication. If a LOCTRANS transformation is needed for these multiple fields, it is necessary to define a restart file for these multiple fields.