3 The remapping (or interpolation or regridding)

**MAPPING**:The

`MAPPING`keyword is used to specify an input file to be read and used for remapping. The`MAPPING`file must follow the`SCRIPR`format (see section 5.4) but can be generated by another library, for example ESMF or XIOS (see details in section 6.3.3). As for the other transformations and interpolations, different mappings can be specified for the different coupling fields. Grid data files*grids.nc*,*masks.nc*, and*areas.nc*are not needed for`MAPPING`.Since OASIS3-MCT_2.0,

`MAPPING`can be used for higher order remapping. Up to 5 different sets of weights (see section 5.4 for the weight file format) can be applied to up to 5 different fields transfered through the`oasis_put`argument (see section 2.2.7).This transformation requires at least one configuring line with one filename and two optional string values:

$MAPNAME $MAPLOC $MAPSTRATEGY

`$MAPNAME`is the name of the mapping file to read. This is a NetCDF file consistent with the SCRIPR map file format (see section 5.4).`$MAPLOC`is optional and can be either`src`or`dst`. With`src`, the mapping will be done in parallel on the source processors before communication to the destination model processes; this is the default. With`dst`, the mapping is done on the destination processes after the source grid data is sent from the source model.`$MAPSTRATEGY`is optional and can be either`bfb`,`sum`, or`opt`. In`bfb`mode, the mapping is done using a strategy that produces bit-for-bit identical results regardless of the grid decompositions; this is the default. With`sum`, the transform is done using the partial sum approach which generally introduces roundoff level changes in the results on different processor counts. Option`opt`allows the coupling layer to choose either approach based on an analysis of which strategy is likely to run faster. Usually, partial sums will be used if the source grid has a higher resolution than the target grid as this should reduce the overall communication (in particular for conservative remapping). By default`$MAPSTRATEGY`=`bfb`.

Note that if

`SCRIPR`(see below) is used to calculate the remapping file,`MAPPING`can still be listed in the`namcouple`, for example to use it with a specific`$MAPLOC`or`$MAPSTRATEGY`option.**SCRIPR**:`SCRIPR`gathers the interpolation techniques offered by Los Alamos National Laboratory SCRIP 1.4 library (Jones 1999)^{10}.`SCRIPR`routines are in`oasis3-mct/lib/scrip`. See the SCRIP 1.4 documentation in`oasis3/doc/SCRIPusers.pdf`for more details on the interpolation algorithms.Since OASIS3-MCT_4.0 release, a hybrid MPI+OpenMP parallel version of the SCRIP library is available. It relies on the MPI parallel layout of the calling model but only uses one MPI process per node. The number of OpenMP threads per MPI process used by SCRIP is set by a dedicated environment variable OASIS_OMP_NUM_THREADS, which can be different from the default number of threads per MPI process used elsewhere in the application, set by the environment variable OMP_NUM_THREADS ; in practice, OASIS_OMP_NUM_THREADS has to be smaller or equal to OMP_NUM_THREADS. For optimum performance, it is recommended to set OASIS_OMP_NUM_THREADS to the number of cores on the node. The

`regrid_environment`directory (see section 6.3.3) in`oasis3-mct/examples/regrid_environment`gives a practical example on how to use the SCRIP library^{11}in parallel to calculate regridding weight-and-address files. The details of the SCRIP parallelisation can be found in (Piacentini et al 2018) and (Valcke et al 2018)^{12}.When the SCRIP library performs a remapping, it first checks if the file containing the corresponding remapping weights and addresses exists; if it exists, it reads them from the file; if not, it calculates them and store them in a file. In the later case, SCRIP needs the grid data files

`grids.nc`and`masks.nc`(see section 5.1). The weight-and-address file is created in the working directory and is by default called`rmp_`,*src*_to_*tgt*_*INTTYPE*_*NORMAOPT*.nc`rmp_`, or*src*_to_*tgt*_*INTTYPE*_*NBR*.nc`rmp_`.*src*_to_*tgt*_*INTTYPE*.nc*src*and*tgt*are the acronyms of respectively the source and the target grids,*INTTYPE*is the interpolation type (i.e.`DISTWGT`,`GAUSWGT`,`GAUSWGTNF`,`DISTWGTNF`,`LOCCUNIF`,`LOCCDIST`,`LOCCGAUS`,`BILINEAR`, -**not BILINEA as in OASIS3.3**,`BILINEARNF`,`BICUBIC`,`BICUBICNF`, or`CONSERV`). Then*NORMAOPT*is the normalization option, for`SCRIPR/CONSERV`only (i.e.`DESTAREA`,`DESTARTR`,`DESTNNEI`,`DESTNNTR`,`FRACAREA`,`FRACARTR`,`FRACNNEI`or`FRACNNTR`, see below).*NBR*is the number of neighbors used for`DISTWGT`,`DISTWGTNF`,`GAUSWGT`,`GAUSWGTNF``LOCCUNIF`,`LOCCDIST`or`LOCCGAUS`only. One has to take care that the remapping file will have the same name even if other details, like the grid masks or the`$MAPLOC`or`$MAPSTRATEGY`options, are changed. When reusing a remapping file, one has to be sure that it was generated in exactly the same conditions than the ones it is used for.The following types of interpolations are available:

`DISTWGT`performs a distance weighted nearest-neighbour interpolation (N neighbours) with a nearest neighbor fill for non-masked target points that do not receive a value. All types of grids are supported.`DISTWGTNF`performs a distance weighted nearest-neighbour interpolation (N neighbours) without the nearest neighbor fill for non-masked target points. All types of grids are supported.The configuring line is:

# SCRIPR (for DISTWGT or DISTWGTNF) $CMETH $CGRS $CFTYP $REST $NBIN $NV $ASSCMP $PROJCART

where:`$CMETH = DISTWGT or DISTWGTNF`.`$CGRS`is the source grid type (`LR`,`D`or`U`)- see appendix A.`$CFTYP`is the field type:`SCALAR`. The option`VECTOR`, which in fact leads to a scalar treatment of the field (as in the previous versions), is still accepted.**VECTOR_I or VECTOR_J (i.e. vector fields) are not supported anymore in OASIS3-MCT**. See “Support of vector fields with the SCRIPR remappings” below.`$REST`is a bin search restriction type:`LATLON`or`LATITUDE`, see SCRIP 1.4 documentation SCRIPusers.pdf.`$NBIN`the number of restriction bins that must be equal to 1 for`DISTWGT, DISTWGTNF, GAUSWGT, GAUSWGTNF, BILINEAR, BILINEARNF, BICUBIC`or`BICUBICNF`(i.e. the bin restriction is not allowed^{13}; for details, see

(Piacentini et al 2018)).`$NV`is the number of neighbours used.`$ASSCMP`,`$PROJCART`: UNUSED;**vector fields are not supported anymore in OASIS3-MCT.**See “Support of vector fields with the SCRIPR remappings” below.

`GAUSWGT`performs a N nearest-neighbour interpolation weighted by their distance and a gaussian function with a nearest neighbor fill for non-masked target points that do not receive a value. All grid types are supported.`GAUSWGTNF`performs a N nearest-neighbour interpolation weighted by their distance and a gaussian function without the nearest neighbor fill for non-masked target points. All grid types are supported.The configuring line is:

# SCRIPR (for GAUSWGT or GAUSWGTNF) $CMETH $CGRS $CFTYP $REST $NBIN $NV $VAR

where all entries are as for`DISTWGT`, except that:`$CMETH = GAUSWGT or GAUSWGTNF``$VAR`defines the weight given to a neighbour source grid point as proportional to where is the distance between the source and target grid points, and where is, for each target grid point, the square of average distance between its source grid points (calculated automatically by OASIS3-MCT).

`LOCCUNIF, LOCCDIST`and`LOCCGAUS`perform a locally conservative interpolation by associating N target nearest neighbours to every SOURCE grid point, and applying a weight normalization taking into account the source/target mesh area ratio. Interpolation weights can additionally be modulated by the source/target distances (`LOCCDIST`) or by the source/target distances and a gaussian function (`LOCCGAUS`). All types of grids are supported. These interpolations are convenient to transfer coupling fields from disjoints areas, such as the river runoff flux, as studied in (Voldoire 2020).The configuring line is:

# SCRIPR (for LOCCUNIF or LOCCDIST) $CMETH $CGRS $CFTYP $REST $NBIN $NV

or# SCRIPR (for LOCCGAUS) $CMETH $CGRS $CFTYP $REST $NBIN $NV $VAR

where:`$CMETH $CGRS $CFTYP $REST $NBIN $NV`entries are as for`DISTWGT`and`$VAR`is as for`GAUSWGT`. Note that for these interpolations,`$NV`represents the number of*target*(and not source) neighbours. For details, see (Maisonnave 2020).

`BILINEAR`performs an interpolation based on a local bilinear approximation (see details in chapter 4 of SCRIP 1.4 documentation SCRIPusers.pdf). Logically-Rectangular (LR) and Reduced (D) source grid types are supported. It also generates regridded values with a nearest neighbor fill for non-masked target points that do not receive any value with the original algorithm.`BILINEARNF`is identical to`BILINEAR`but without the nearest neighbor fill.`BICUBIC`performs an interpolation based on a local bicubic approximation for Logically-Rectangular (LR) grids (see details in chapter 5 of SCRIP 1.4 documentation SCRIPusers.pdf), and on a 16-point stencil for Gaussian Reduced (D) grids. Note that for Logically-Rectangular grids, 4 weights for each of the 4 enclosing source neighbours are required corresponding to the field value at the point, the gradients of the field with respect to*i*and*j*, and the cross gradient with respect to*i*and*j*in that order. OASIS3-MCT will calculate the remapping weights and addresses (if they are not already provided) but will not, at run time, calculate the two gradients and the cross-gradient of the source field (as was the case with OASIS3.3). These 3 extra fields need to be calculated by the source code and transfered as extra arguments of the`oasis_put`(see`fld2, fld3, fld4`in section 2.2.7). Finally, this interpolation will fill non-masked target points that do not receive a value with a nearest neighbor fill.`BICUBICNF`is identical to`BICUBIC`but without the nearest neighbor fill.For

`BILINEAR`,`BILINEARNF`,`BICUBIC`, and`BICUBICNF`, the configuring line is:# SCRIPR (for BILINEAR, BILINEARNF, BICUBIC, or BICUBICNF) $CMETH $CGRS $CFTYP $REST $NBIN

where:`$CMETH = BILINEAR`,`BILINEARNF`,`BICUBIC`, or`BICUBICNF``$CGRS`is the source grid type: LR or D.`$CFTYP`,`$REST`,`$NBIN`are as for`DISTWGT`.

Note that for

`DISTWGT`,`GAUSWGT`,`BILINEAR`and`BICUBIC`:- Masked target grid points: the zero value is associated to
masked target grid points.
- Non-masked target grid points having some of the source
points normally used in the interpolation
masked: a N nearest neighbour algorithm using the remaining non
masked source points is applied.
- Non-masked target grid points having all source
points normally used in the interpolation
masked: by default, the nearest non-masked source
neighbour is used (
`ll_nnei`is set to`.true.`in the SCRIP run).

Note that for

`DISTWGTNF`,`GAUSWGTNF`,`BILINEARNF`and`BICUBICNF`:- Identical behavior to non-NF options but no nearest non-masked source
neighbour fill is done (
`ll_nnei`is set to`.false`in the SCRIP run). Non-masked target grid points that do not receive any interpolated value are set to 0 .

`CONSERV`performs 1st or 2nd order conservative remapping, which means that the weight of a source cell is proportional to area intersected by the target cell (plus some other terms proportional to the gradient of the field in the longitudinal and latitudinal directions for the second order).The configuring line is:

# SCRIPR (for CONSERV) $CMETH $CGRS $CFTYP $REST $NBIN $NORM $ORDER $NTHRESH $STHRESH

where:`$CMETH = CONSERV``$CGRS`is the source grid type: LR, D and U. Note that the grid corners have to given by the user in the grid data file`grids.nc`or by the code itself in the initialisation phase by calling routine`oasis_write_corner`(see section 2.2.4) ; OASIS3-MCT will not attempt to automatically calculate them as OASIS3.3.`$CFTYP, $REST`are as for`DISTWGT`.`$NBIN`is the number of restriction bins that can be more than 1 as bin restriction is effectively allowed for`CONSERV`; for details, see (Piacentini et al 2018).`$NORM`is the normalization option:`FRACAREA`or`FRACARTR`: The sum of the non-masked source cell intersected areas is used to normalise each target cell field value: the flux is not locally conserved, but the flux value itself is reasonable. With`FRACARTR`, an additional correction involving the “true" area of the grid cells provided in the file`areas.nc`is also applied, see details in the paragraph on the “True Area” (TR) correction below.`FRACNNEI`or`FRACNNTR`: as`FRACAREA`or`FRACARTR`, except that an additional unmasked source nearest neighbour is used for unmasked target cells that intersect only masked source cells.`DESTAREA`or`DESTARTR`: The total target cell area is used to normalise each target cell field value even if it only partly intersects non-masked source grid cells: local flux conservation is ensured, but unreasonable flux values may result. With`DESTARTR`, an additional correction involving the “true" area of the grid cells provided in the file`areas.nc`is also applied, see details in the paragraph on the “True Area” (TR) correction below.`DESTNNEI`or`DESTNNTR`: as`DESTAREA`or`DESTARTR`, except that an additional unmasked source nearest neighbour is used for unmasked target cells that intersect only masked source cells.

`$ORDER`:`FIRST`or`SECOND`for first or second order conservative remapping respectively (see SCRIP 1.4 documentation).For

`CONSERV/SECOND`, 3 weights are needed; OASIS3-MCT will calculate these weights and corresponding addresses (if they are not already provided) but will not, at run time, calculate the two extra terms to which the second and third weights should be applied. These terms, respectively the gradient of the field with respect to the latitude () and the gradient of the field with respect to the longitude () need to be calculated by the source code and transferred as extra arguments of the`oasis_put`as`fld2`and`fld3`respectively (see section 2.2.7). Note that`CONSERV/SECOND`is not positive definite.`$NTHRESH`is the value of the northern latitude threshold in radians where conservative area computation switches from linear boundaries in longitude and latitude at the equator to a Lambert equivalent azimuthal projection toward the north pole. This value is optional and the default is 2.0 radians (greater than 90 degrees) which means the Lambert projection is never invoked. If this value is set,`$STHRESH`must be set as well.`$STHRESH`is the value of the southern latitude threshold in radians where conservative area computation switches from linear boundaries in longitude and latitude at the equator to a Lambert equivalent azimuthal projection toward the south pole. This value is optional and the default is -2.0 radians (less than -90 degrees) which means the Lambert projection is never invoked. If this value is set,`$NTHRESH`must be set as well.

**Precautions related to the use of the SCRIPR/CONSERV remapping**- Lambert projection above/below
`north_thresh`/`south_thresh`For the 1st order conservative remapping, the weight of a source cell is proportional to area of the source cell intersected by target cell. Using the divergence theorem, the SCRIP library evaluates this area with the line integral along the cell borders enclosing the area. As the real shape of the borders is not known (only the location of the corners of each cell is known), the library assumes that the borders are linear in latitude and longitude between two corners. This assumption becomes less valid closer to the pole.

Therefore for latitudes above the

`north_thresh`or below the`south_thresh`values (see`oasis3-mct/lib/scrip/remap_conserv.F90`), the library evaluates the intersection between two border segments using a Lambert equivalent azimuthal projection.**However, by default,**(Note thatand**north_thresh**are set to 2.0 and -2.0 radians respectively and the Lambert projection is not activated.**south_thresh**`north_thresh`was set to 1.45 in previous versions prior to OASIS3-MCT_4.0.)The value of the north and south threshhold can be defined in the namcouple file via the

`$NTHRESH`and`$STHRESH`optional settings on the SCRIPR input line.(Valcke and Piacentini 2019) analyses the impact of the Lambert projection for specific grids.

- Another limitation of the SCRIP 1st order conservative
remapping algorithm is that it assumes, for line integral
calculation, that is linear in longitude on the
cell borders which again is in general not valid close to the
pole.
- For a proper consevative remapping, the corners of a cell have
to coincide with the corners of its neighbour cell, with no
“holes” between the cells.
- Overlying cells
If two cells of one same grid overlay, the one with the greater numerical index must be masked in

*masks.nc*for a proper conservative remapping. For example, if the grid cells with*i=1*overlays the grid cells with*i=imax*, the latter must be masked. If none of overlying cells is masked (given the original mask defined in*masks.nc*), OASIS3-MCT must be compiled with the CPP key`TREAT_OVERLAY`which will ensure that these rules are respected. This CPP key was introduced in OASIS3.3. - Masked (non-active) target grid cells are set to 0.
- If a target grid cell intersects only masked source cells, or falls outside the source grid domain, it
will get a zero value unless the
`DESTNNEI`,`DESTNNTR`,`FRACNNEI`, or`FRACNNTR`normalisation options are used, in which case it will get the source nearest non masked neighbour value. Note that the option of having the value 1.0E+20 assigned to these target grid cell intersecting only masked source cells (for easier identification) is not yet availble in OASIS3-MCT.

**The “True Area” (TR) correction:**,**DESTARTR**,**DESTNNTR**, or**FRACARTR****FRACNNTR**The approximations and hypotheses adopted by the SCRIP impact its estimation of the grid cell areas. Therefore, to have an exact conservation of the field surface-integrated values, a correction based on the "TRue" (TR) area of the cells can be applied by choosing

`DESTARTR`,`DESTNNTR`,`FRACARTR`or`FRACNNTR`options. These are based respectively on`DESTAREA`,`DESTNNEI`,`FRACAREA`and`FRACNNEI`normalisations adding the so-called “TR correction”. The true area of the cell, i.e. the one considered by the component model itself, must be provided in the auxiliary file*areas.nc*in**square radians**. Equations from (Chavas et al 2013) (eqn. (27) in particular) are implemented.Special care is taken in the implementation for “polar" cells in the SCRIP sense. The SCRIP detects cells encompassing a pole or cells with a side going through a pole as “polar" cells and a specific treatment is applied for those cells modifying its area. The resulting estimated area serves as a normalisation factor but its value is not representative of the surface of the cell anymore. For this reason, the TR correction is not activated for those “polar” cells.

More details can be found in section 6 of (Valcke and Piacentini 2019). A full validation of the TR correction can be found in that report. It is noted there that the TR correction always improves the results even if, in the cases tested, the misfit between the true area and the are evaluated by the SCRIP is always small (except for “polar” cells of course).

**Support of vector fields with the SCRIPR remappings**Vector mapping is NOT supported and will not be supported by OASIS3-MCT. For proper treatment of vector fields, the source code has to send the 3 components of the vector projected in a Cartesian coordinate system as separate fields. The target code has to receive the 3 interpolated Cartesian components and recombine them to get the proper vector field.

**INTERP**: UNUSED**MOZAIC**: UNUSED; note that`MAPPING`(see above) is the NetCDF equivalent to`MOZAIC`.**NOINTERP**: UNUSED**FILLING**: UNUSED

- ...Jones99
^{10} - See also http://climate.lanl.gov/Software/SCRIP/ and the copyright statement in appendix 1.3.3.
- ... library
^{11} - The
`regrid_environment`directory provides a practical example on how to calculate the regridding weight-and-address files with the SCRIP library but also with ESMF and XIOS, see section 6.3.3 - ...valcke11
^{12} - A few bugs were fixed in the SCRIP library available since OASIS3-MCT_4.0 release, in particular in the bounding box definition of the grid cells. This solves an important bug observed in the Pacific near the equator for the bilinear and bicubic interpolations for Cartesian grids. However, given these modifications, one cannot expect to get exactly the same results for the weight-and-address remapping files with this new parallel SCRIP version as compared to the previous SCRIP version in OASIS3-MCT_3.0. We checked in many different cases that the interpolation error is smaller or of the same order than before. We also observed that the parallelisation does not ensure bit reproducible results when varying the number of processes or threads.
- ... allowed
^{13} - The only exceptions are for Gaussian Reduced (
`D`) grids for (`BILINEAR, BILINEARNF, BICUBIC`and`BICUBICNF`; in that case,**if the Gaussian-reduced grid is stored from North to South**the number of bins is the number of latitude circles of the grid (minus one, to be precise), independently of`$NBIN`;**for Gaussian-reduced grid stored from South to North to South, the bin definition will not work and the interpolation will become a 4 distance-weighted nearest-neighbour for all target points.**