The purpose of the package is to remap variables from a native grid, e.g EUR-44 or EUR-11 or ALP-3, to the respective regular grid,
e.g.  EUR-44i or EUR-11i or ALP-3i, and thereby taking care that variables with a strong land-sea contrast retain this property.

Thus, the actual remapping tool is organized such that the land->land and sea->sea remapping is kept separated.
It is implicitly supposed that the native and the target regular grids have comparable resolution, if this is not met it is not known whether result is still reliable.

In the end there will always be some grid cells in the regular grid (small island surrounded by sea, relatively small lakes surrounded by land) that will not be filled.
For those  cells the tool applies (as a kind of afterburner) an unconstraint remapping (disregarding the land-sea aspect), in order avoid undefined numbers on the regular grid.

For both the native and the regular grid the tool is built on one generic mask, i.e. the land sea mask.
For the regular grid (EUR-44i or EUR-11i or ALP-3i) this is a respective common mask, for the native grid it is the respective land sea mask corresponding to the RCM.

There might be some  variables with an "extreme" land-water contrast.
"extreme" here means that these variables are only defined over land but not over any kind of water body (open sea, rivers, lakes).
At least in CCLM (COSOM-CLM) these variables are represented by the missing value (=1.E20) at grid points over water.
In CCLM these variables are: snc snd mrros mrro mrso1 mrso.
This "extreme" land-water contrast is kept also in the target grid depending on the land-sea mask of the target domain.

For the remapping procedure weight files have to be created, but only once per RCM and destination domain.
This will be done before the actual remapping
Thus, the user has to choose now one variables and one frequency (e.g. day or sem) for which CMORized data on the native grid are available.
Attention!!!!
If you carried out already a remapping to some destination domain and if you now want to perform another remapping to different destination domain,
and if you define the same scratch directories $HWD and $SWD
be sure that the directories $HWD and $SWD are empty. Previously created weight files are stored in $SWD, but they do not correspond to the new destiantion domain
Attention!!!!
I don't recommend to choose a variable from the list of "Variables_with_missing_value_over_water" (see above, HJP's opinion)
only a variable should be chosen that does not have any missing value in the native grid

Note:
Before you run the remapping procedure please check whether the sftlf values related to the native grid are really given in percent ( 0<= sftlf <=100)!

Further information are given as comments within the steering script "EUR_CORDEX_Remapping.sh"

The whole consists of:
  - steering script "EUR_CORDEX_Remapping.sh"
  - script "create_weights.sc "to create fields of weights; has to be done only once
  - script "create_fx.sh "to create files of orography and land-Sea fraction for destination grid
  - actual remapping/interpolation script "doremap.sc " ("do remapping")

 three input data sets must exist:
  1.: On the native grid the already CMORized data that should be interpolated/remapped
  2.: On the native grid the already CMORized fixed (fx) fields of orog (orography in m)  and sftlf (Land_Sea_Fraction in %)
  3.: On target grid orog_sftlf_${destDomain}.nc containing orography (orog in m) and land-sea fraction (sftlf units=1) of the target/destination domain
      has to be created before performing the interpolation/remapping
      It is a good advice that different modelers who want to interpolate/remap their data to the same target/destination grid share this file orog_sftlf_${destDomain}.nc
      ${destDomain} stands for the name of the target/destination domain, e.g ALP-3i
      The package contains three of these files:
      - orog_sftlf_ALP-3i.nc    ; should be used for the remapping of FPS Convection data 
      - orog_sftlf_EUR-44i.nc   ; had been used for the remapping of  EUR-44 data
      - orog_sftlf_EUR-11i.nc   ; had been used for the remapping of  EUR-11 data

How to create the common orog_sftlf_${destDomain}.nc:
     have a look into "orog_sftlf_ALP-3i.nc" using ncdump -h; the history at the end shows a way to do it

Note:
    in common orog_sftlf_${destDomain}.nc the land-sea fraction sftlf MUST not be given in percent! 
    Here range of vlaues has to be: 0 <= sftlf <= 1

Furthermore, one finds:
- the PDF "instruction_remapping_tool.pdf" written by Erik van Meijgaard in 2015 for the use of the original tool and its application within EURO-CORDEX
- an example for a batch-script, "EUR_CORDEX_Remapping.batch", here valid for CRAY XC40 at HLRS, Stuttgart, Germany

 Important notes:
 Please, have a thorough look at the comments within the steering script "EUR_CORDEX_Remapping.sh", which gives more information on the application and possible "traps"

Authors:
  - steering script "EUR_CORDEX_Remapping.sh" and sript "create_weights.sc" and script "create_fx.sh" written by Hans-Juergen Panitz (HJP), IMK/KIT, Sep/Oct 2019
  - actual interpolation script "doremap.sc" written by Erik van Meijgaard and colleagues, KNMI; has been modified by H.-J. Panitz


Now finally, here are some numbers concerning the performance of the tool when running it as batch job on CRAY XC40 at HLRS, Stuttgart.
I remapped my FPS evaluation data for the simulation period 2000 until 2014 (15 years).
I considered much more variables per frequency and more frequencies than actually required for the Convection FPS

frequency               remarks                                          time needed
  1hr         1 variable, 5 yearly files simultaneously                  about  60 min
              for more than 5 files I got memory problems
  3hr        30 variables, 15 yearly files simultaneously                about 130 min
  6hr        12 variables, 15 yearls files simultaneously                about  37 min
  day        70 variables, 4 files simultaneously, chunked into          about 210 min
                           1y/5y/5y/4y chunks, respectively              
  mon        70 variables, 3 files simultaneously, chunked into          about  19 min
                           1y/10y/5y chunks, respectively
  sem        70 variables, 3 files simultaneously, chunked into          about  18 min
                           1y/10y/5y chunks, respectively


A "special" variable might be CIN (and perhaps also others).
At least for CCLM, this variable might have grid points with missing value (1.E20), which are distributed inhomogeneously over the whole source grid.
This means, the missing values are not constrained to grid points representing any kind of water body only.
The tool is able to treat such a variable, but the remapping might take quit a long time.
Here are a few numbersa and remarks. I did not consider sub-daily frequencies!!

frequency               remarks                                          time needed
  day        1 variable, 15 yearly files simultaneously                about 120 min
                missing values are still present, I don't recommend
                chunking of daily data before the remapping                       
                chunked files might become rather large and remapping
                would take much more time; 
                5 hours computing time were not enough
  mon        1 variable, 3 files simultaneously, chunked into          about   4 min
                           1y/10y/5y chunks, respectively
                no missng values anymore due to the consideration of 
                monthly averages
  sem        1 variable, 3 files simultaneously, chunked into          about   9 sec
                           1y/10y/5y chunks, respectively
                no missng values anymore due to the consideration of 
                seasonal averages



H.-J. Panitz, KIT/IMK-TRO, October 2019
Update October 2020




