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