==Introduction==

In order to '''intercompare different models''', they must be interpolated from the native grid on which they were calculated to a common output grid. This procedure is known as '''regridding or remapping'''.

Fundamentally, '''regridding consists of two steps''':

 # Creation of an interpolation matrix (weights file), which gives the amount that each point on the source grid contributes to each point on the target grid. These weights will depend on the type of interpolation desired. ISMIP6 has standardized on First-order Conservative Remapping (Jones, P.W. 1999, Monthly Weather Review, 127, 2204-2210), which does a better job preserving fluxes (or other integrals) than, eg., bilinear interpolation.
 # For each point on the target grid, sum the data values on the source grid multiplied by the corresponding weights. The same weights file may be used for more than one input variable, provided all are defined on the same source grid.
Different software may do one or the other or both of these steps.

To create the weights file, you must have ''grid description files'' for your source and target grids. These files give the latitudes and longitudes of every grid point, along with the corners of the boundary of its surrounding cell. There are several ways to write these files, depending on the software you're using.

Will Roberts (University of Bristol) has had success regridding '''BISICLES''' output using [https://earthsystemmodeling.org/regrid/ ESMF] to generate weights and [https://nco.sourceforge.net/ NCO] to calculate the regridded data values. This page is adapted from notes provided by Will. ESMF is also the tool used by CESM and CISM, and some tips used by CISM are included below, thanks to Jeremy Fyke. There is also an ESMF python interface, [https://earthsystemmodeling.org/esmpy/ ESMPy] (ESMF Python Regridding Interface), although we have not tested this ourselves. 

'''Note''': ''For simplicity, the most of the directories shown below are the original ones from Will's notes, and refer to U. Bristol's installations. Remember to adapt them for your own situation!''

(Image(ice_sheet_image_thin.png))

==Aim==
Take a BISICLES hdf5 file (an unstructured grid) and regrid it to the 5km ISMIP6/!SeaRISE structured grid in !NetCDF (.nc) format.

Making sure that the data are in a SCRIP format seems to make things run smoothly.

'''Steps'''
 # Convert B.hdf5 into B.nc
 # Create SCRIP type grid description file
 # Create ESMF weights for Greenland_5km_v1.1.nc
 # Regrid B.nc into B_2.nc using the esmf weights make

==hdf5 → nc==
Use amr2CF in BISICLES/code/filetools/amrtocf.cpp
{{{
cd /data/ggslc/opt/BISICLES/BISICLES/code/filetools
amrtocf2d.Linux.64.g++.gfortran.DEBUG.ex config.amrtocf infile=plot.GrIS.1km.l1l2.4lev.017584.2d.hdf5 outfile=~/ismip6/plot.nc
}}}

==Create SCRIP grid description file==
At present amr2CF won't produce SCRIP-type grid files. Thus you need to mangle the output a little to get SCRIP compatible files. Principally this requires the grid corner matrix to go in a circle (i.e. enclose the grid box) and the grid bits need to be renamed:
 * grid_corner_lat
 * grid_corner_lon
 * grid_center_lon
 * grid_center_lat
 * grid_dims
 * grid_imask

'''Note''': You need to have the dimensions grid_corners – how many corners there are to your grid and grid_rank which in our case is just 1 and used by grid_dims, which tells us how many grid boxes we have (this is the same as grid_size in our case).

'''Example''' matlab code of how to generate a SCRIP compatible file for CESM and CISM is available on the ftp server (see SCRIP_matlab_stuff.zip in /ISMIP6/initMIP/grid_description_files/SCRIP). Feedback to Jeremy Fyke is welcomed.

For information about SCRIP and access to SCRIP-format grid description files, contact ismip6@gmail.com

==Build ESMF==
ESMF's home page is at https://www.earthsystemcog.org/projects/esmf/.

On Macintoshes, ESMF can be easily installed via the !MacPorts package manager at https://www.macports.org/. !MacPorts will also automatically install any other libraries ESMF requires.

For other systems, after downloading and unpacking the source distribution,

'''Note''': Directories shown below are those used at U. Bristol. Adapt to your own installation.
{{{
export ESMF_DIR="/home/paleo/ggwhgr/esmf"
export ESMF_NETCDF_LIBPATH="/data/ggslc/opt/lib"
export ESMF_NETCDF="split"
export ESMF_NETCDF_INCLUDE="/data/ggslc/opt/include"
export ESMF_NETCDF_LIBS="-lnetcdf -lnetcdff"
export ESMF_LAPACK_LIBPATH="/data/ggslc/opt/lib"
export ESMF_LAPACK_INCLUDE="/data/ggslc/opt/include/"
export ESMF_LAPACK_LIBS="-llapack -lblas"

make
}}}
'''Note''': At Goddard, we also needed to specify `export ESMF_F90COMPILEPATHS="-I/usr/include"` to tell gfortran where to find the netcdf.mod file.


==Use ESMF to create the weights file==
Change directories to where ESMF installed its executable files; this may be somewhere beneath `esmf/DEFAULTINSTALLDIR/`, but the subdirectory will depend on which architecture and compiler you used. 
Then,
{{{
./ESMF_RegridWeightGen -s ~/ismip6/new_bike.nc -d ~/ismip6/SCRIPgrid_gland_5km_c150511.nc -m conserve -i --src_regional --dst_regional --check  -w ~/ismip6/wts.nc
}}}
'''where:'''

`-s`
where is the source grid. This is the file created by scrip_from_plot.m in the step above.

`-d`
where is the destination grid. SCRIPgrid_gland_5km_c150511.nc is a SCRIP grid description file for the standard Greenland 5 km polar-stereographic grid.

`-m conserve` 
does a conservative regridding

`-i` 
ignores unmapped destination points

`--src_regional --dst_regional`
indicates the source and destination grids are not global (seems to work with global too)

`--check`
runs a check after calculating weights – ensures they actually work

`-w` 
where do you want the weight file

==References:==

Grid File Formats [https://earthsystemmodeling.org/docs/release/ESMF_8_1_1/ESMF_refdoc.pdf (ESMF Reference Manual, section 12.8)]

ESMF_!RegridWeightGen [https://earthsystemmodeling.org/docs/release/ESMF_8_1_1/ESMF_refdoc.pdf (ESMF Reference Manual, section 12.9)]

==Use NCO to apply weights to input file, giving regridded output file==
The NCO home page is at http://nco.sourceforge.net/. For information on regridding with NCO, see http://nco.sourceforge.net/nco.html#Regridding.

'''Note''': Requires nco ≥ 4.5.0 (released June 2015)

`ncks --map=wts.nc --rgr col_nm=grid_size new_bike.nc out.nc`

'''where:'''

`--map=wts.nc`
regrid input file to output file, using wts.nc (created with ESMF_!RegridWeightGen in the step above) as the weight (map) file.

`--rgr col_nm=grid_size`
name of the dimension to be used for the unstructured output grid

`new_bike.nc `
input data file, defined on source grid

`out.nc`
output file, data regridded to target grid