First section of namcouple file

The first section of namcouple uses some predefined keywords prefixed by the $ sign to locate the related information. The $ sign must be in the second column. The first ten keywords are described hereafter:

• $SEQMODE: On the line below this keyword is the maximum value of the coupling field SEQ index specified in the namcouple (or 1 if no SEQ indices are specified for the coupling fields, see below and also section 4.8).

• $CHANNEL: On the line below this keyword is the communication technique chosen. Choices are MPI1 or MPI2 for the CLIM communication technique and related PSMILe library. To run OASIS3 as an interpolator only, put NONE (see also section 6.1). The communication techniques available in previous OASIS version, i.e. SIPC, PIPE, or GMEM are not officially supported anymore.

  To use the CLIM/MPI2 communication technique, the lines below $CHANNEL are, e.g. for 3 models:

   
  $CHANNEL 
  MPI2 NOBSEND
  1    1  arg1 
  3    1  arg2
  3    1  arg3
  

  where MPI2 is the message passing used in CLIM and PSMILe, and NOBSEND indicates that standard basic send MPI_Send should be used in place of the default buffered MPI_BSend to send the coupling fields. The standard basic send MPI_Send can be used only if the coupling fields are sent and received in the same order by the different component models, i.e. the order into which they are listed in the namcouple, or on platforms for which MPI_Send is implemented with a sufficiently large mailbox. The less efficient default buffered send MPI_BSend should be used on platforms for which MPI_Send is not implemented with a mailbox⁷ if the coupling fields are not sent and received in the order into which they are listed in the namcouple⁸.

  The following lines (one line per model listed on the $NBMODEL line) indicate for each model the total number of processes, the number of processes implied in the coupling, and possibly launching arguments⁹. Here the first model runs on one process which is of course implied in the coupling and the argument passed to the model is "arg1"; the second and third models run on 3 processes but only one process is implied in the coupling (i.e. exchanging information with OASIS3 main process), and the argument passed to the models are respectively ``arg2" and ``arg3''.

  To use the CLIM/MPI1 communication technique, the $CHANNEL lines are as for MPI2 except that MPI2 is replaced by MPI1 and there is no launching arguments. With MPI1, models have to be started by the user in a pseudo-MPMD mode in the order they are introduced in the namcouple. The way to do this depends on the computing platform. With MPI1, OASIS3 main process and the component models automatically share the same MPI_COMM_WORLD communicator; in this communicator OASIS3 main process is assumed to have rank 0 and the other component models are assumed to have ranks in the order of which they are introduced in namcouple. If this is not the case, a deadlock may occur.

• $NFIELDS: On the line below this keyword is the total number of fields exchanged and described in the second part of the namcouple.

  In some cases, an additional number has to be specified on the same line after the total number of fields exchanged. This number, corresponding to the maximum number of prism_def_var_proto called by ANY component model in the coupled system, is mandatory if it is greater than twice the number of fields listed in the namcouple; this may be the case if OASIS3 is used in IPSL parallel mode (see section 8.2.1) or if fields declared with prism_def_var_proto call in the component code are not activated in the namcouple (in this case, the corresponding sending and receiving calls in the component code simply return without any action performed).

• $JOBNAME: On the line below this keyword is a CHARACTER$\star$3 or CHARACTER$\star$4 variable giving an acronym for the given simulation.

• $NBMODEL: On the line below this keyword is the number of models running in the given experiment followed by CHARACTER$\star$6 variables giving their names, which must correspond to the name announced by each model when calling prism_init_comp_proto (second argument, see section 4.1). In MPI2 mode, these names also have to correspond to the model executable names.

  Then the user may indicate the maximum Fortran unit number used by the models. In the example, Fortran units above 55, 70, and 99 are free for respectively the ocean, atmosphere, and atmospheric chemistry models. If no maximum unit numbers are indicated, OASIS3 PSMILe will suppose that units above 1024 are free. If $CHANNEL is NONE, $NBMODEL has to be 0 and there should be no model name and no unit number.

• $RUNTIME: On the line below this keyword is the total simulated time of the run, expressed in seconds. If $CHANNEL is NONE, $RUNTIME has to be the number of time occurrences of the field to interpolate from the restart file.

• $INIDATE: On the line below this keyword is the initial date of the run. The format is YYYYMMDD. This date is important only for the FILLING transformation and for printing information in OASIS3 log file cplout.

• $MODINFO: If coupling restart files are binary files (see section 7.3), the line below this keyword indicates if a header is encapsulated or not: it can be YES or NOT.

• $NLOGPRT: The line below this keyword refers to the amount of information that will be written to the OASIS3 log file cplout during the run. With 0, there is practically no output written to the cplout; with 1, only some general information on the run, the header of the main routines, and the names of the fields when treated appear in the cplout. Finally, with 2, the full output is generated.

• $CALTYPE: This keyword gives the type of calendar used. The calendar type is important only if FILLING analysis is used for a coupling field in the run and for printing information in OASIS3 log file cplout. Below this keyword, a number (0, 1 or n ) must be indicated by the user:
  • 0 : a 365 day calendar (no leap year)
  • 1 : a 365 or 366 (leap years) day calendar A year is a leap year if it can be divided by 4; however if it can be divided by 4 and 100, it is not a leap year; furthermore, if it can be divided by 4, 100 and 400, it is a leap year.
  • n : $n \ge 1$ day month calendar.

Footnotes

... mailbox⁷

Note that it was observed that the MPI_Bsend does not work correctly on NEC SX8 with MPI libraries versions 7.2.0 et 7.2.1; this problem was solved with MPI version 7.2.4.

...namcouple⁸

Note that below the call to prism_enddef_proto, the PSMILe tests whether or not the model has already attached to an MPI buffer. If it is the case, the PSMILe detaches from the buffer, adds the size of the pre-attached buffer to the size needed for the coupling exchanges, and reattaches to an MPI buffer. The model own call to MPI_Buffer_Attach must therefore be done before the call to prism_enddef_proto. Furthermore, the model is not allowed to call MPI_BSend after the call to prism_terminate_proto, as the PSMILe definitively detaches from the MPI buffer in this routine. See the example in the atmoa3.F90 model in oasis3/examples/toyoa3/atmoa3/src.

... arguments⁹

The cases that have been fully tested are: 1- when all processes participate in the coupling; 2- when only the master process participate in the coupling. The case where a subset of more than one process participate in the coupling has not been tested.