The remapping (or interpolation or regridding)

**MAPPING**:The

`MAPPING`keyword is used to specify an input file to be read and used for mapping (ie. regridding or interpolation); the`MAPPING`file must follow the`SCRIPR`format (see section 5.4). In this case grids.nc, masks.nc and areas.nc files are not needed, except if the post-procession global option CONSERV is used in the namcouple. Then the user must provides the areas.nc file.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 (e.g. for conservative remapping).

Note that if

`SCRIPR`(see below) is used to calculate the remapping file,`MAPPING`can still be listed in the`namcouple`to specify a name for the remapping file generated by`SCRIPR`different from the default and/or to specify a`$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.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. The file is created in the working directory and is by default called

`rmp_`, where*srcg*_to_*tgtg*_*INTTYPE*_*NORMAOPT*.nc*srcg*and*tgtg*are the acronyms of respetively the source and the target grids,*INTTYPE*is the interpolation type, i.e.`DISTWGT`,`GAUSWGT`,`BILINEAR`(**not BILINEA as in OASIS3.3**) or`CONSERV`-see below, and*NORMAOPT*is the normalization option, i.e.`DESTAREA`,`FRACAREA`or`FRACNNEI`for`CONSERV`only -see below). 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). All types of grids are supported.- Masked target grid points: the zero value is associated to
masked target grid points.
- Non-masked target grid points having some of the N source
nearest neighbours masked: a nearest neighbour algorithm using
the remaining non masked source nearest neighbours is applied.
- Non-masked target grid points having all of the N source
nearest neighbours masked: by default, the nearest non-masked
source neighbour is used (logical
`ll_nnei`hard-coded to`.true.`in`oasis3-mct/lib/scrip/src/remap_distwgt.F`; same default behaviour as OASIS3.3).

The configuring line is:

# SCRIPR (for DISWGT) $CMETH $CGRS $CFTYP $REST $NBIN $NV $ASSCMP $PROJCART

where:`$CMETH = DISTWGT`.`$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 the search restriction type:`LATLON`or`LATITUDE`(see SCRIP 1.4 documentation SCRIPusers.pdf).`$NBIN`the number of restriction bins (see SCRIP 1.4 documentation SCRIPusers.pdf). Note that for D or U grid, the restriction with more than 1 bin is not allowed : choose LATLON or LATITUDE and $NBIN=1`$NV`is the number of neighbours used.`$ASSCMP`: UNUSED;**vector fields are not supported anymore in OASIS3-MCT.**See ``Support of vector fields with the SCRIPR remappings'' below.`$PROJCART`: UNUSED;**vector fields are not supported anymore in OASIS3-MCT.**See ``Support of vector fields with the SCRIPR remappings'' below.

- Masked target grid points: the zero value is associated to
masked target grid points.
`GAUSWGT`performs a N nearest-neighbour interpolation weighted by their distance and a gaussian function. All grid types are supported.- Masked target grid points: the zero value is associated to
masked target grid points.
- Non-masked target grid points having some of the N source
nearest neighbours masked: a nearest neighbour algorithm using
the remaining non masked source nearest neighbours is applied.
- Non-masked target grid points having all of the N source
nearest neighbours masked: by default, the nearest non-masked
source neighbour is used (logical
`ll_nnei`hard-coded to`.true.`in`oasis3-mct/lib/scrip/src/remap_gauswgt.f`);**this is NOT the same default behaviour as OASIS3.3**; to have the same default behaviour as in OASIS3.3, put`ll_nnei=.false.`.

The configuring line is:

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

where: all entries are as for`DISTWGT`, except that:`$CMETH = GAUSWGT``$VAR`, which must be given as a REAL value (e.g 2.0 and not 2), 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 the average distance between two source grid points (calculated automatically by OASIS3-MCT).

- Masked target grid points: the zero value is associated to
masked target grid points.
`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.`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 gradient of the field with respect to*i*, the gradient of the field with respect to*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).For both

`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 bilinear or bicubic interpolation
masked: a N nearest neighbour algorithm using the remaining non
masked source points is applied.
- Non-masked target grid points having all bilinear or bicubic
neighbours masked: by default, the nearest non-masked source
neighbour is used (
`ll_nnei`hard-coded to`.true.`in`oasis3-mct/lib/scrip/src/remap_bilinear.f`,`remap_bicubic.f`and`remap_bicubic_reduced.F90`);**this is not the same default behaviour as OASIS3.3**; to have the same default behaviour as in OASIS3.3, put`ll_nnei=.false.`in the appropriate routine.

For both

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

where:`$CMETH = BILINEAR`or`BICUBIC``$CGRS`is the source grid type: LR or D.`$CFTYP`,`$NBIN`are as for`DISTWGT`.`$REST`is as for`DISTWGT`, except that only`LATITUDE`is possible for a Reduced (D) source grid.

- Masked target grid points: the zero value is associated to
masked target grid points.
`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

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`,`$NBIN`are as for`DISTWGT`.`$NORM`is the NORMalization option:`FRACAREA`: 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.`DESTAREA`: 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.`FRACNNEI`: as`FRACAREA`, except that at least the source nearest unmasked neighbour is used for unmasked target cells that intersect only masked source cells. Note that a zero value will be assigned to a target cell that does not intersect any source cells (masked or unmasked), even with FRACNNEI option.

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

`CONSERV/SECOND`, 3 weigths 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 longitude () and the gradient of the field with respect to the latitude () need to be calculated by the source code and transfered as extra arguments of the`oasis_put`(see`fld2, fld3`in section 2.2.7). Note that`CONSERV/SECOND`is not positive definite and has not been fully validated yet.

**Precautions related to the use of the SCRIPR/CONSERV remapping**- 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 4 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; for latitudes above the
`north_thresh`or below the`south_thresh`values (see`oasis3-mct/lib/scrip/remap_conserv.F`, the library evaluates the intersection between two border segments using a Lambert equivalent azimuthal projection. Problems were observed in some cases for the grid cell located around this`north_thresh`or`south_thresh`latitude. - Another limitation of the SCRIP 1st order conservative
remapping algorithm is that is also supposes, 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.
- 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. - A target grid cell intersecting no source cell (either masked
or non masked) at all i.e. falling in a ``hole'' of the source
grid will get the non-masked nearest-neighbour value.
- If a target grid cell intersects only masked source cells, it
will still get a zero value unless the
`FRACNNEI`normalisation option is used, in which case it will get the 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.**

**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 received 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.