Writes the description of an unstructured grid to an ESMF file.
Available in version 6.1.0 and later.
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl" load "$NCARG_ROOT/lib/ncarg/nclscripts/esmf/ESMF_regridding.ncl" procedure unstructured_to_ESMF ( ESMF_filename  : string, lat : numeric, lon : numeric, opt  : logical )
Name of ESMF NetCDF file to write.lat
The lat/lon arrays representing the unstructured grid.opt
An optional variable to set certain attributes for this procedure. If set to False, none of the attributes will have an effect.
See below for a full list of attributes.
This procedure writes the description of a an unstructured grid to an ESMF description file.
unstructured_to_ESMF is part of a suite of regridding routines based on Earth System Modeling Framework (ESMF) software. The regridding can be done via a multi-step process that includes this procedure, or via an "all-in-one" function called ESMF_regrid.
Both methods have their advantages. The multi-step process involves:
- Creating the description NetCDF file for the source grid.
- Creating the description NetCDF file for the destination grid.
- Calculating and writing the weights to a NetCDF file.
- Applying the weights to regrid the data from the source grid to the destination grid.
- Copying attributes and coordinates to the newly regridded variable.
The ESMF_regrid function performs all of the above steps.
The attributes that can be attached to opt include:
- Mask2D (no default)
A mask array of the same size as the desired lat/lon grid, that
indicates which areas to mask out (that is, which values are
missing). Set the masked (missing) areas to 0, and all the rest to 1.
If these masks are different across multiple levels or timesteps, then you will need to generate a separate weights file for each level or timestep where it changes. See the special note below.
- Overwrite (default = False)
If set to True, then if the description NetCDF file exists, you
will be prompted for whether to remove it.
- ForceOverwrite (default = False)
If set to True, then the description NetCDF file will be
overwritten no matter what.
- InputFileName (no default)
Optional: name of the file containing the unstructured grid.
- LargeFile (default = False)
If set to True, then the NetCDF file will be written in "large
- PrintTimings (default = False)
Print the CPU time spent in this routine.
- Debug (default = False) Turn on debug prints.
You can use the same weights file to regrid across other levels and timesteps of the same variable, or across other variables, as long as the lat/lon grid that you are regridding from and to are exactly the same, and, if you use the special Mask2D option, that your masks are exactly the same. The masks are 2D arrays filled with 0's and 1's that indicate where your data values and/or lat/lon values are missing. Here's a description from Robert Oehmke of ESMF about this:
What the mask does is remove the entity (cell or point depending on the type of regridding) from consideration by the regridder. If it's a source cell then no destination entities are mapped to it. If it's a destination entity, then it's not interpolated to. There is a little more in-depth discussion in the ESMF reference manual.
Right now, masking needs to be done before weight calculation so the regridding knows what it should ignore, so if the mask changes then you need to regenerate weights. We actually have a feature request ticket for handling this type of missing value situation more fluidly. The plan is to have the interpolation automatically not use missing values when they are encountered in a data field. Which would allow the same weights to be used for all the levels.
One trick you can do right now with missing values and a weight file is to do two interpolations to tell you where the missing values will spread in the destination field. First interpolate a field containing all 0's except for where the missing values are set the missing value locations to 1, the result of this interpolation tells you which destination locations (the ones whose values >0.0) will be affected by the missing values, so you can ignore them after interpolating the data. (You could also do something like this in one step during the data interpolation if you have a restricted range for your data and you use a value way outside that range for your missing value.) This, of course, will give you a coarser result than using the masking, but will probably be more efficient than recalculating the weights each time.