2 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 the first non-blank character on the line but can be in any column. 8 keywords are used by OASIS3-MCT and 5 of these are optional :

• $NFIELDS: On the line below this keyword, put a number equal (or greater) to the total number of field entries in the second part of the namcouple. If more than one field are described on the same line, this counts as only one entry.

• $RUNTIME: On the line below this keyword, put the total simulated time of the run, expressed in seconds (or any other time units as long as the same are used in all components and in the namcouple, see 2.2.7).

• $NLOGPRT: The first and second numbers on the line below this keyword refer to the amount of debug and time statistic information written by OASIS3-MCT for each component and process.

  The first number (that can be modified at runtime with the oasis_set_debug routine, see section 2.2.9) may be:

  • 0 : production mode. One file debug.root.xx is open by the master process of each component and one file debug_notroot.xx is open for all the other processes of each component to write only error information.
  • 1 : one file debug.root.xx is open by the master process of each component to write information equivalent to level 10 (see below) and also to write memory usage information; one file debug_notroot.xx is open for all the other processes of each component to write error information.
  • 2 : one file debug.yy.xxxxxx is open by each process of each component (with “yy” being the component number and “xxxxxx” the process number) to write normal production diagnostics and memory usage information
  • 5 : as for 2 with in addition some initial debug info
  • 10: as for 5 with in addition the routine calling tree
  • 12: as for 10 with in addition some routine calling notes
  • 15: as for 12 with even more debug diagnostics
  • 20: as for 15 with in addition some extra runtime analysis
  • 30: full debug information
  The second number defines how time statistics are written out to file comp_name.timers_xxxx (with comp_name being the component name, see section 2.2.2); it can be:
  • 0 : nothing is calculated or written.
  • 1 : some time statistics are calculated and written in a single file by the processor 0 as well as the min and the max times over all the processors.
  • 2 : some time statistics are calculated and each processor writes its own file ; processor 0 also writes the min and the max times over all the processors in its file.
  • 3 : some time statistics are calculated and each processor writes its own file ; processor 0 also writes in its file the min and the max times over all processors and also writes in its file all the results for each processor.
  For more information on the time statistics written out, see section 6.4.2.

  The second number can also be set to -1 to activate the lucia tool that can be used to perform an analysis of the coupled components load balance. More information can be found in the README file in oasis3-mct/util/lucia directory and report mentioned therein.

• $NUNITNO: Optional (new in OASIS3-MCT_4.0); on the line below this keyword are two integers that indicate the minimum and maximum unit numbers to be used for input and output files in the coupling layer. The user should choose values that will NOT conflict or overlap with unit numbers in use in any of the component models. The defaults are 1024 for the minimum and 9999 for the maximum unit number if not explicitly set by the user.

• $NMAPDEC: Optional (new in OASIS3-MCT_4.0); on the line below this keyword is a character string that indicates the mapping decomposition value to be used during local mapping. The options are decomp_1d and decomp_wghtfile. Option decomp_1d decomposes the grid in a simple one dimensional way while decomp_wghtfile decomposes the grid using the information in the remapping weight file to reduced mapping communication. Option decomp_wghtfile will take some extra time in initialization but it should result in faster mapping. The default is decomp_1d but it is recommended to test decomp_wghtfile to see if that option improves performance. More details can be found in (Craig et al 2018) and in (Valcke et al 2018).

• $NMATXRD: Optional (new in OASIS3-MCT_4.0); on the line below this keyword is a character string that indicates the method used to read remapping weights. There are two options, orig and ceg. In both, the weights are read in chunks by the root process. In the orig option, the weights are then broadcasted to all processes and each process then saves the weights needed in order to be consistent with the mapping decomposition. In the ceg option, the root process reads the weights and then decides which process each weight should be assigned to. A series of exchanges are then done and just the weights needed on each process are sent. The orig method sends much more data but is more parallel. The ceg method does most of the work on the root process but less data is communicated. The default option is ceg. More details can be found in (Craig et al 2018).

• $NWGTOPT : Optional (new in OASIS3-MCT_4.0); on the line below this keyword is a character string that indicates how to handle bad remapping weights. There are four options
  abort_on_bad_index, ignore_bad_index, ignore_bad_index_silently, and
  use_bad_index. Bad weights are defined as weights in the mapping file for which either the source or destination index are out of bounds relative to the number of grid cells in the grid; in that case, the weight is referencing a gridcell that does not physically exist. Note that an index equal to zero will not be considered as a bad index if the associated weight is also zero. There are other situations where the value of the actual mapping weight is scientifically incorrect, but this is not easy to detect and is not dealt with in OASIS3-MCT.
  • abort_on_bad_index will write error messages to the log files and abort if a bad weight index is detected. This is the default option.
  • ignore_bad_index will write an error message and then remove bad weights internally before continuing.
  • ignore_bad_index_silently will remove bad weights and continue without writing an error message.
  • use_bad_index will attempt to keep bad weights in the interpolation computation, but this can result in memory corruption, silent dropping of weights, and incorrect results ; this is not recommended.

  Note that the ability to check mapping files at runtime in OASIS3-MCT is limited. It is always recommended that mapping files be analyzed offline before long production runs are carried out. Checks can be done to make sure the source and destination indices are valid, that weights values are reasonable (for instance, between 0 and 1, although this will depend on the mapping method), and that the sum of weights on the destination cells are reasonable (for instance, 1, in many cases). In addition, offline tests can be run with analytical functions to verify conservation, gradient preserving features and other characteristics associated with the particular mapping approach.

• $NNOREST: Optional (new in OASIS3-MCT_4.0); on the line below this keyword is a character string that can override the requirement that restart files must exist if they are needed. If the character string value starts with T, t, .T, or .t (as in true), then OASIS3-MCT will initialise with zero any variable that normally requires a restart (for instance, variables with LAG $>$ 0) if the restart file does not exist. By default, missing restart files will cause the model to abort. It is strongly recommended that this keyword NOT be used in production runs. It exists to provide a quick shortcut for running technical tests. Note that if $NNOREST is true but the restart file nonetheless exists, it will be used.

• Keywords $SEQMODE, $CHANNEL, $JOBNAME, $NBMODEL, $INIDATE, $MODINFO, $CALTYPE: are not used anymore.