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). As for the other transformations and interpolations, different mappings can be specified for the different coupling fields. In this case grids.nc, masks.nc and areas.nc files are not needed, except if the post-procession global option CONSERV is specified 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 (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 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)⁹. 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.

  New in OASIS3-MCT_4.0, an hybrid MPI+OpenMP parallel version of the SCRIP library is available. It relies on the MPI parallel layout of the calling model but only enrols one MPI process per node. The number of OpenMP threads per node is set by a dedicated environment variable OASIS_OMP_NUM_THREADS, and for optimum performance, it is recommended to set this variable to the number of cores of the node. The test_interpolation environment (see section 6.3.3) in oasis3-mct/examples/test_interpolation gives a practical example on how to use the SCRIP library in parallel to calculate remapping weight-and-address files. The details of the SCRIP parallelisation can be found in (Piacentini et al 2018) and (Valcke et al 2018)¹⁰ .

  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_srcg_to_ tgtg_INTTYPE_NORMAOPT.nc, where 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 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.

    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 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, GAUSWGT, BILINEAR or BICUBIC i.e. the bin restriction is not allowed¹¹; 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. All grid types are supported.

    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 defines the weight given to a neighbour source grid point as proportional to $exp(-1/2 \cdot d^2/\sigma^2)$ where $d$ is the distance between the source and target grid points, and $\sigma^2 = \$VAR \cdot \overline{D}^2$ where $\overline{D}^2$ is, for each target grid point, the square of average distance between its source grid points (calculated automatically by OASIS3-MCT).

  • 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 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).

    For 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, $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 hard-coded to .true. in corresponding SCRIP sources).

  • 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 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: 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 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 ($\theta$) $\frac{\delta f}{\delta \theta}$ and the gradient of the field with respect to the longitude ($\phi$) $\frac{1}{cos \theta}\frac{\delta f}{\delta \phi}$ 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.

  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 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.F90, the library evaluates the intersection between two border segments using a Lambert equivalent azimuthal projection. However, problems were observed in some cases for the grid cell located around this north_thresh or south_thresh latitude. So by default, north_thresh and south_thresh are now in OASIS3-MCT_4.0 by default set to 2.0 and -2.0 respectively, where as north_thresh was set to 1.45 in previous versions.

  • Another limitation of the SCRIP 1st order conservative remapping algorithm is that is supposes, for line integral calculation, that $sin(latitude)$ 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.

  • If a target grid cell intersects only masked source cells, it will 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.

  • With FRACNNEI 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.

  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

Footnotes

...Jones99⁹

See also http://climate.lanl.gov/Software/SCRIP/ and the copyright statement in appendix 1.3.3.

...valcke11¹⁰

Thanks to some preliminary work, few bugs were fixed in the SCRIP library, 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 interpolation weight-and-adress 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¹¹

The only exceptions are for Gaussian Reduced (D) grids for ( BILINEAR and BICUBIC; 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.