8. To go further¶
8.1. OASIS¶
8.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.).
8.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
8.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
8.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.
8.2. 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.
8.2.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*
8.2.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.
8.2.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.
8.2.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.
8.2.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.
8.2.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.
8.2.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.
8.3. Toy model¶
8.3.1. What is the toy model?¶
The toy model that has been developed for the Meso-NH/SurfEx coupling with OASIS is inspired by the toy models available in the OASIS tutorial. It has been completely rewritten in version 570 of Meso-NH. This toy model simulates an ocean or wave model that can be coupled with Meso-NH. There is no physics involved in this model, which simply sends and receives fields without modifying them. Among other things, it can be used to test the coupling algorithm used.
8.3.2. Toy model tree structure¶
The tree structure of the toy model and the various calls to OASIS functions are presented here:
-- toy_model.F90
|-- OASIS *oasis_init_comp*
|-- OASIS *oasis_get_localcomm*
|-- read_namelist.F90
|-- read_dimgrid.F90
|-- read_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*
|-- decomp_def.F90
|-- OASIS *oasis_def_partition*
|-- OASIS *oasis_def_var*
|-- OASIS *oasis_enddef*
|** start time-stepping **
|-- OASIS *oasis_get*
|-- get_values_to_send.F90
|-- read_forcing.F90
|-- OASIS *oasis_put*
|** end of time-stepping **
|-- OASIS *oasis_terminate*
8.3.3. Toy model compilation¶
In the toy folder there are :
readme : a documentation file
Makefile : the makefile for the toy model
*.F90 : the source files
The toy model supplied with Meso-NH is compiled automatically when Meso-NH is compiled (like OASIS) but it may be necessary to modify it and then recompile it.
To compile the toy model manually, do
cd src/
. ../conf/profile_mesonh
make toy
8.3.4. Description of the TOYNAMELIST.nam¶
To use the toy model, you also need to create a TOYNAMELIST.nam with the following namelists :
&nam_grid
Name |
Type |
Default |
Signification |
|---|---|---|---|
ntime_steps |
INTEGER |
- |
Nb of time step |
time_step |
REAL |
- |
Time step [s] |
grid_file_name |
CHARACTER(LEN=30) |
- |
Grid file name |
&nam_fct_send
Name |
Type |
Default |
Signification |
|---|---|---|---|
type_send |
CHARACTER(LEN=5) |
- |
Type of field send to Meso-NH (‘cnste’, ‘sinus’, ‘files’) |
forcing_file_name |
CHARACTER(LEN=30) |
- |
If type_send = ‘files’, forcing_file_name is the name of the netcdf file. |
value_send |
REAL |
- |
If type_send = ‘cnste’, value_send corresponds to the value of the field which will be homogeneous over the zone.
If type_send = ‘sinus’ then value_send will be equal to the amplitude of the sine.
|
&nam_recv_fields
Name |
Type |
Default |
Signification |
|---|---|---|---|
nrecv_fields |
INTEGER |
- |
Nb of fields received by the toy model |
name_recv_fields |
CHARACTER(LEN=8,
DIM=nrecv_fields)
|
- |
OASIS name for the fields received by the toy model |
Note
name_recv_fields name must the same as the one in namcouple and must be 8 characters long
&nam_send_fields
Name |
Type |
Default |
Signification |
|---|---|---|---|
nsend_fields |
INTEGER |
- |
Nb of fields send by the toy model |
name_send_fields |
CHARACTER(LEN=8,
DIM=nsend_fields)
|
- |
OASIS name for the fields send by the toy model |
Note
name_send_fields name must the same as the one in namcouple and must be 8 characters long
8.3.4.1. TOYNAMELIST.nam example¶
Below is an example of a 3600s simulation, with a time step of 60s. The grid and mask definition file is called grid_toy_model.nc. The 3 fields sent come from the file named wave.nc. The OASIS identifiers for the 3 fields sent are: VARSND01, VARSND02 and VARSND03. 2 fields are received by the toy and have identifiers VARRCV01 and VARRCV02.
&nam_grid ntime_steps=60,
time_step=60,
grid_file_name='grid_toy_model.nc' /
&nam_fct_send type_send='files',
forcing_file_name='wave.nc',
value_send=10 /
&nam_recv_fields nrecv_fields=2,
name_recv_fields(1)='VARRCV01',
name_recv_fields(2)='VARRCV02' /
&nam_send_fields nsend_fields=3,
name_send_fields(1)='VARSND01',
name_send_fields(2)='VARSND02',
name_send_fields(3)='VARSND03' /