7. To go further

7.1. OASIS

7.1.1. Introduction

The information presented in this section is described in detail in the OASIS user guide (https://verc.enes.org/oasis/). The OASIS source code is either available in the Meso-NH version in the src/LIB/oasis3-mct_5.0/ folder (if you are using a Meso-NH version greater than or equal to 5.3.0) or by downloading it from the OASIS website.

To sum up, OASIS3-MCT is fully parallelized, has no executable specific to the coupler, is capable of managing 2d and 3d coupling field exchanges, is capable of supporting unstructured meshes, is capable of transferring fields in parallel, across all source or target component processes, has a namelist that allows the coupling characteristics to be changed without having to recompile the codes (type of interpolation, simulation duration, exchange time, etc.).

7.1.2. Installation and compilation

In the folder containing the OASIS code (src/LIB/oasis3-mct_5.0/), following directories are presented:

doc/                 : Documentation
lib/                 : Libraries : mct, psmile and scrip
pyoasis/             : API for python
util/load_balancing/ : Tools for load balancing analysis
util/make_dir/       : Makefiles

It is important to compile OASIS with the same libraries (NetCDF, MPI, etc.) as those that will be used that will be used for the code you wish to couple. So, if you decide to change one of these libraries, you will have to recompile OASIS and the codes with this new library.

To compile OASIS manually, you need to modify the make.inc file in the util/make_dir folder according to the desired libraries, then run the following commands:

cd oasis_dir/util/make_dir/
make realclean -f TopMakefileOasis3
make -f TopMakefileOasis3

7.1.3. Functions implemented in models

Using OASIS involves an instrumentation phase which consists of placing the various calls to the OASIS3-MCT routines in the codes (in this case Meso-NH and TOY). The use of a specific precompilation key is used if you want to compile Meso-NH linking to OASIS. This key is called CPLOASIS.

OASIS3-MCT is used in the following phases:

• initialisation phase:

  • oasis_init_comp : initialization of the coupling

  • oasis_get_localcomm : creation by OASIS3-MCT of a local (to the model) MPI communicator. This new communicator must be used throughout the model (a precompilation key is used to force the model to use this communicator in the case of a coupled run).

• definition of interpolation grids:

  The interpolation methods used in OASIS call files created during this step. Once defined, the interpolation grids are stored in netcdf files: grids.nc, area.nc and mask.nc. These files contain the grids for all the coupled models. The OASIS functions used in this step are:

  • oasis_start_grids_writing : starts writing grid files, masks, …

  • oasis_write_grid defines model grids (essential for CONSERV or SCRIP interpolation).

  • oasis_write_corner defines the corners of model grids: essential for CONSERV or SCRIP interpolation.)

  • oasis_write_mask defines the mask.

  • oasis_write_area which defines the area of the meshes

  • oasis_terminate_grids_writing which is used to finish writing.

  At the end of these stages, netcdf files are generated by OASIS: grids.nc, areas.nc and masks.nc with information about the different grids. The creation of these files is completed by calling the oasis_enddef routine, which is located after the local partitions have been defined. The creation of the grids requires the variables to be in global physical space (without the halo).

• definition of local partitions:

  description of the local partitions of each of the processes in the space of global indexes:

  • oasis_def_partition: with the following main arguments:

    • ig_paral: used to describe local partitions, in particular to say whether in the case of sequential or parallel execution, and in the second case, what type of partition it is

    • isize: used to specify the size of the global grid for which data is data is actually exchanged. This optional parameter is important, particularly when, for a given model, certain parts of its domain are not are not included in the calculation. For example, for an ocean model land points are excluded from the calculation but are still part of the grid. OASIS is able to manage this situation thanks to this parameter.

  At the end of this step, netcdf files with weights for interpolations (remapping) from one grid to another are generated: rmp*.nc.

• declaration of coupling fields:

  declare the fields that will be received and sent. These fields must all be identified in the namcouple described below. To do this, use the function:

  • oasis_def_var

• end of initialisation phase:

  • oasis_enddef: the grid definition files are created at this point.

• exchange of coupling fields:

  calls to the routines that allow to send and receive data are placed in the model time-stepping.

  • oasis_get : at the beginning of the loop to receive fields.

  • oasis_put : at the end of the time loop, to send fields.

  The coupled models cannot start at the same time because the fields are received at the beginning of the time loop (before they are sent). It is therefore necessary to time-shift (the notion of LAG, which will be described later) the coupled models so that each oasis_get coincides with an oasis_put and vice versa. The fields received by the model which first makes an oasis_get will come from a previously created rstrt.nc files.

• end of coupling:

  • oasis_terminate

7.1.4. Description of the namcouple

The namcouple file is the namelist for the OASIS coupler, which contains all the information relating to exchanges between models. It follows a syntax which is clearly explained in the OASIS3-MCT user manual. There are no blank lines! Since there is no syntax check on this file, the slightest error will result in a crash with no error indication.

First of all, we need to declare the general parameters of the coupled simulation: the number of coupling fields, the number of models, the name of the models (identical to what is given to OASIS via the oasis_init_comp routine): mesonh (for Meso-NH) and toyexe (for the toy model), the duration of the simulation in seconds (it has to be the same for both models).

All these parameters are used to write the first part of the namcouple.

# This is a typical input file for OASIS3-MCT.
# Keywords used in previous versions of OASIS3
# but now obsolete are marked "Not used"
# Don't hesitate to ask precisions or make suggestions (oasishelp@cerfacs.fr).
#
# Any line beginning with # is ignored. Blank lines are not allowed.
#
#########################################################################
$NFIELDS
# The number of fields described in the second part of the namcouple.
#
            2
$END
#########################################################################
$NBMODEL
# The number of models in this experiment + their names (6 characters)
#
  2  mesonh   toyexe
$END
###########################################################################
$RUNTIME
# The total simulated time for this run in seconds
#
 70
$END
###########################################################################
$NLOGPRT
# Amount of information written to OASIS3-MCT log files (see User Guide)
# Premier nombre: quantite d'information pour debugger
# Second nombre: statistics des processeurs
 30 3
$END

The second part of the namcouple concerns exchanges between models. You need to have a precise idea of the coupling algorithm you want to implement. you want to implement. First of all, we need to decide on a coupling period for the different fields.

It is not possible to give a coupling period shorter than the largest time step of the models. In addition, the coupling period must be proportional to the model time steps and must be positive; reals are not allowed. OASIS only sends data when a send date corresponds to a receive date, It is therefore necessary to ensure that the coupling period is such that the two models can “meet”.

You also need to choose the type of interpolation for the transition from one grid to another.

Note

It is possible to choose different exchange periods and interpolations for each exchanged field.

We are particularly interested in the namcouple parameters for the exchange of SST exchange in the context of the coupling between Meso-NH and TOY. This case is sufficiently generic to be adapted to other exchanges:

#~~~~~~~~~~~
# Field 1 : SEA SURFACE TEMPERATURE
#~~~~~~~~~~~
(l.1) TOY__SST MNH__SST 1 10 3 rstrt.nc EXPOUT
(l.2) 321 194 100 87 toy mnht LAG=+10
(l.3) R 0 R 0
(l.4) LOCTRANS BLASOLD SCRIPR
(l.5) AVERAGE
(l.6) 1.0 1
(l.7) CONSTANT 273.15
(l.8) BILINEAR LR SCALAR LATLON 1

• (l.1) : here we have the field identifier, with the one on the source side (TOY__SST) and then the one on the target side (MNH__SST). The following parameter is not used but must be present to ensure compatibility with the older version of OASIS. Next, we have the coupling period for this exchange (10 seconds), the number of operations that will be applied to this field, the name of the restart file and the status of the field.

• (l.2) : the dimensions of the source (toyt) and target (mnht) grids, their names and the value of the LAG where applicable. if applicable. The grids here are those in the grids.nc, masks.nc and areas.nc files.

• (l.3) : characteristics of the source and target grids (“R”: regional and “0”: no overlapping overlap of grid points).

• (l.4 à 8) : list of operations to be performed on this field, followed by the parameters for each of these operations:

  • LOCTRANS : temporal transformation - AVERAGE (l. 5)

  • BLASOLD: multiplication of the field by 1 (l. 6) to which is added the value 273.15 (l. 7): conversion from Kelvin to Celsius.

  • SCRIPR: interpolation whose parameters are supplied (l. 8): in this case bilinear interpolation

Note

You need to repeat this block for each coupling fields.

7.2. LAG concept

The figure ref{fig:coupled_simulation} shows an example of a coupled simulation between an atmospheric model and an ocean model to introduce the LAG concept explained in detail in the OASIS documentation. The purpose of this diagram is to present the role of the files rstrt_SAVE.nc (rst_A.nc and rst_O.nc) which you will have to create in the chapter concerning the preparation of configurations (Chapter ref{ch:prepa_config}). \

At the initial instant (t=ini), the atmospheric and oceanic models receive the coupling fields located in the rtsrt.nc files. As soon as the models reach a simulation time that is a multiple of the exchange time (at t=exchange time), the models exchange the fields. At the end of the simulation (at t=end), the exchanged fields are stored in the rstrt.nc files, which can be used at the start of the next simulation. \

Note

Note that the fields contained in the rstrt.nc files will be overwritten at the end of the simulation, so it is important to copy them and not to make a symbolic link to these files if you wish to keep a trace of the files used to initialise this simulation. \

7.3. Meso-NH/SurfEx

77 functions have been modified/created to cover the implementation of coupling in Meso-NH/SurfEx: 9 functions concern Meso-NH and 66 SurfEx. These functions are described in the routines. Only the tree structure and the steps for compiling Meso-NH are described in this section.

7.3.1. Tree structure of Meso-NH/SurfEx

-- mesonh.f90
  |-- sfx_oasis_init.f90
      |-- OASIS *oasis_init_comp*
      |-- OASIS *oasis_get_localcomm*
  |-- init_mnh.f90
      |-- init_ground_paramn.f90
          |-- init_surf_atmn.f90
              |-- init_sean.f90
                  |-- init_seafluxn.f90
  |-- sfx_oasis_read_nam.f90
  |-- mnh_oasis_grid.f90
      |-- OASIS *oasis_start_grids_writing*
      |-- OASIS *oasis_write_grid*
      |-- OASIS *oasis_write_corner*
      |-- OASIS *oasis_write_area*
      |-- OASIS *oasis_write_mask*
      |-- OASIS *oasis_terminate_grids_writing*
  |-- mnh_oasis_define.f90
      |-- sfx_oasis_define.f90
          |-- OASIS *oasis_def_partition*
          |-- OASIS *oasis_def_var*
          |-- OASIS *oasis_enddef*
  |** start time-stepping **|
  |-- modeln.f90
  |-- phys_paramn.f90
      |-- ground_paramn.f90
          |-- mnh_oasis_recv.f90
              |-- sfx_oasis_recv.f90
                  |-- OASIS *oasis_get*
              |-- put_sfxcpln.f90
                  |-- put_sfx_land.f90
                  |-- put_sfx_sea.f90
                  |-- put_sfx_wave.f90
          |** go to SurfEx **|
          |-- coupling_surf_atmn.f90
              |-- coupling_sean.f90
                  |-- coupling_seaflux_orogn.f90
                      |-- coupling_seawat_sbln.F90
                          |-- coupling_seafluxn.f90
                              |-- coare30_seaflux.f90
                                  |-- coare30_flux.f90
          |** end of SurfEx **|
          |-- mnh_oasis_send.f90
              |-- get_sfx_lake.f90
              |-- get_sfx_land.f90
              |-- get_sfx_sea.f90
              |-- get_sfx_wave.f90
              |-- sfx_oasis_send.f90
                  |-- OASIS *oasis_put*
   |** end of time-stepping **|
   |-- sfx_oasis_end.f90
       |-- OASIS *oasis_terminate*

7.3.2. Preparing initial files for Meso-NH

The coupling only affects the simulation (MESONH executable). The initial Meso-NH files for a simulation are therefore obtained in the same way as for a forced simulation. as for a forced simulation. The initial files will come from the PREP_PGD and PREP_REAL_CASE or PREP_IDEAL_CASE stages.

It is necessary to have an rstrt.nc file which will allow the model starting first, which needs to receive a field via oasis_get, to read the field in the rstrt.nc file. This rstrt.nc file can be created using the python script used in KTEST.

7.3.3. Description of the EXSEG1.nam

Namelists specific to the coupling have been created and are presented below. The other namelists for EXSEG1.nam are identical to an uncoupled simulation.

7.3.3.1. &NAM_OASIS

Name	Type	Default	Signification
LOASIS	LOGICAL	.False.	Activate OASIS
LOASIS_GRID	LOGICAL	.False.	Create grids and rmp files
CMODEL_NAME	CHARACTER	‘mesonh’	Model name

Note

CMODEL_NAME name must the same as the one in namcouple.

7.3.3.2. &NAM_SFX_SEA_CPL

Name	Type	Default	Signification
XTSTEP_CPL_SEA	REAL	-1.0	Coupling time-step for oceanic fields
CSEA_FWSU	CHARACTER(LEN=8)	-	OASIS name for the u-momentum flux (send)
CSEA_FWSV	CHARACTER(LEN=8)	-	OASIS name for the v-momentum flux (send)
CSEA_HEAT	CHARACTER(LEN=8)	-	OASIS name for the non-solar heat flux (send)
CSEA_SNET	CHARACTER(LEN=8)	-	OASIS name for the solar flux (send)
CSEA_WIND	CHARACTER(LEN=8)	-	OASIS name for the wind speed (send)
CSEA_FWSM	CHARACTER(LEN=8)	-	OASIS name for the momentum flux (send)
CSEA_EVAP	CHARACTER(LEN=8)	-	OASIS name for the evaporation flux (send)
CSEA_RAIN	CHARACTER(LEN=8)	-	OASIS name for the rain flux (send)
CSEA_SNOW	CHARACTER(LEN=8)	-	OASIS name for the snow flux (send)
CSEA_WATF	CHARACTER(LEN=8)	-	OASIS name for the freshwater flux (send)
CSEA_PRES	CHARACTER(LEN=8)	-	OASIS name for the surface pressure (send)
CSEA_SST	CHARACTER(LEN=8)	-	OASIS name for the sea surface temperature (received)
CSEA_UCU	CHARACTER(LEN=8)	-	OASIS name for the u-surface current (received)
CSEA_VCU	CHARACTER(LEN=8)	-	OASIS name for the v-surface current (received)

Note

• The CSEA_* character strings correspond to the OASIS names of the variables exchanged between the ocean and the atmosphere and must be identical to those present in the namcouple. This identifier must be 8 characters long. An empty space of 8 characters corresponds to the default value: no exchange of this variable.

• XTSTEP_CPL_SEA equal to -1 indicates no coupling with the ocean.

7.3.3.3. &NAM_SFX_WAVE_CPL

Name	Type	Default	Signification
XTSTEP_CPL_WAVE	REAL	-1.0	Coupling time-step for wave fields
CWAVE_U10	CHARACTER(LEN=8)	-	OASIS name for the 10m u-wind speed (send)
CWAVE_V10	CHARACTER(LEN=8)	-	OASIS name for the 10m v-wind speed (send)
CWAVE_CHA	CHARACTER(LEN=8)	-	OASIS name for the Charnock coefficient (received)
CWAVE_UCU	CHARACTER(LEN=8)	-	OASIS name for the u-surface current (received)
CWAVE_VCU	CHARACTER(LEN=8)	-	OASIS name for the v-surface current (received)
CWAVE_HS	CHARACTER(LEN=8)	-	OASIS name for the significant wave height (received)
CWAVE_TP	CHARACTER(LEN=8)	-	OASIS name for the peak period (received)

Note

• The CWAVE_* character strings correspond to the OASIS names of the variables exchanged between the oceanic wave and the atmosphere and must be identical to those present in the namcouple. This identifier must be 8 characters long. An empty space of 8 characters corresponds to the default value: no exchange of this variable.

• XTSTEP_CPL_WAVE equal to -1 indicates no coupling with the oceanic wave.

• The choice of the parameterisation of turbulent fluxes with waves is made with &NAM_SEAFLUXn NGRWAVES and is only available with CSEA_FLUX=’COARE3’. Please refer to the SURFEX documentation for more details.

7.3.3.4. Example namelist EXSEG1.nam for an Ocean-Wave-Atmosphere coupling

Below is an example of a namelist for a simulation with Meso-NH. The creation of the grids is desired during the simulation. The model identifier is “mesonh” and this name must be identical to that of the namcouple. Coupling with wave and ocean models is desired. Fields with identifiers are exchanged every 100s.

&NAM_OASIS LOASIS=.TRUE.,
           LOASIS_GRID=.TRUE.,
           CMODEL_NAME='mesonh' /

&NAM_SFX_SEA_CPL XTSTEP_CPL_SEA  =  100.,
                 CSEA_FWSU       = 'MNH_FMSU',
                 CSEA_FWSV       = 'MNH_FMSV',
                 CSEA_HEAT       = 'MNH_HEAT',
                 CSEA_SNET       = 'MNH_SNET',
                 CSEA_WIND       = '        ',
                 CSEA_FWSM       = '        ',
                 CSEA_EVAP       = 'MNH_EVAP',
                 CSEA_RAIN       = 'MNH_RAIN',
                 CSEA_SNOW       = '        ',
                 CSEA_WATF       = '        ',
                 CSEA_PRES       = 'MNH_PRES',
                 CSEA_SST        = 'MNH__SST',
                 CSEA_UCU        = 'MNH_UCUR',
                 CSEA_VCU        = 'MNH_VCUR' /

&NAM_SFX_WAVE_CPL XTSTEP_CPL_WAVE = 100.0,
                  CWAVE_U10       = 'MNH__U10',
                  CWAVE_V10       = 'MNH__V10',
                  CWAVE_CHA       = 'MNH__CHA',
                  CWAVE_US        = 'MNH___US',
                  CWAVE_VS        = 'MNH___VS',
                  CWAVE_HS        = 'MNH___HS',
                  CWAVE_TP        = 'MNH___TP' /

&NAM_DIAG_SURFn N2M=2 /

Note

You need to use &NAM_DIAG_SURFn N2M=2 / namelist in order to compute sea surface fluxes. The rest of the namelist is identical to the case without coupling.