Regridders

Simulations often need to import external data directly onto the computational grid. The Regridders module implements different schemes to accomplish this goal.

Currently, Regridders comes with two implementations:

  1. TempestRegridder uses TempestRemap (through ClimaCoreTempestRemap) to perform conservative interpolation onto lat-long grids. TempestRegridder only works for single-threaded CPU runs and works directly with files.
  2. InterpolationsRegridder uses Interpolations.jl to perform non-conservative linear interpolation onto lat-long(-z) grids. InterpolationsRegridder works directly with data.

⚠️ Note: While the Regridders can be used independently, most users will find their needs are immediately met by the SpaceVaryingInputs and TimeVaryingInputs interfaces. These higher-level objects implement everything that is needed to read a file to the model grid (internally using the Regridders).

If a regridder type is not specified by the user, and multiple are available, the InterpolationsRegridder will be used by default. At least one regridder extension must be loaded to be able to use regridding.

TempestRegridder

This extension is loaded when loading ClimaCoreTempestRemap

TempestRegridder performs conservative interpolation of lat-lon grids onto computational domains. TempestRegridder performs all the interpolation ahead of time and saves the regridded fields to HDF5 files that can be read during the simulation.

Example

Assuming target_space is a ClimaCore 2D spherical field, the input data is the variable u in the file era5_example.nc, and we want to read the data associated with date target_date.

import ClimaUtilities.Regridders
import ClimaCoreTempestRemap
# Loading ClimaCoreTempest automatically loads TempestRegridder

reg = Regridders.TempestRegridder(target_space, "regrid_output", "u", "era5_example.nc")
# When reg is created, the variable `u` is regridded and the output files
# are saved to the `regrid_output` folder

regridded_u = Regridders.regrid(reg, target_date)

InterpolationsRegridder

This extension is loaded when loading ClimaCore and Interpolations

InterpolationsRegridder performs linear interpolation of input data (linear along each direction) and returns a ClimaCore Field defined on the target_space.

Currently, InterpolationsRegridder only supports spherical shells and extruded spherical shells (but it could be easily extended to other domains).

Note: it is easy to change the spatial interpolation type and extrapolation conditions, if needed.

InterpolationsRegridder are created once, they are tied to a target_space, but can be used with any input data. With MPI runs, every process computes the interpolating function. This is always done on the CPU and moved to GPU for accelerated runs.

Example

Assuming target_space is a ClimaCore 2D spherical field.

import ClimaUtilities.Regridders
import ClimaCore, Interpolations
# Loading ClimaCore and Interpolations automatically loads InterpolationsRegridder

reg = Regridders.InterpolationsRegridder(target_space)

# Now we can regrid any data
lon = collect(-180:1:180)
lat = collect(-90:1:90)
# It has to be lon, lat (because this is the assumed order in the CF conventions)
dimensions = (lon, lat)

data = rand((length(lon), length(lat)))

interpolated_data = Regridders.InterpolationsRegridder(reg, data, dimensions)
interpolated_2data = Regridders.InterpolationsRegridder(reg, 2 .* data, dimensions)

API

ClimaUtilities.Regridders.TempestRegridderFunction
TempestRegridder(target_space::ClimaCore.Spaces.AbstractSpace,
                 input_file::AbstractString,
                 regrid_dir::AbstractString,
                 varname::AbstractString,
                 regrid_dir::AbstractString;
                 mono::Bool)

Set up a TempestRegridder object to regrid the variable in the given input_file to the target_space. TempestRegridder works only on CPU and on a single process.

Positional arguments

  • target_space: the ClimaCore Space where the simulation is being performed.
  • input_file: the path of the NetCDF file that has to be read and processed.
  • regrid_dir: the path where to save the regrid files created by TempestRemap.
  • varname: the name of the variable in the NetCDF file.
  • regrid_dir: a folder where regridded Fields are saved as HDF5 files.

Keyword arguments

  • mono: Whether remapping has to be monotonic or not.
ClimaUtilities.Regridders.InterpolationsRegridderFunction
InterpolationsRegridder(target_space::ClimaCore.Spaces.AbstractSpace
                        [; extrapolation_bc::Tuple])

An online regridder that uses Interpolations.jl

Currently, InterpolationsRegridder is only implemented for LatLong and LatLongZ spaces. It performs linear interpolation along each of the directions (separately). By default, it imposes periodic boundary conditions for longitude, flat for latitude, and throwing errors when extrapolating in z. This can be customized by passing the extrapolation_bc keyword argument.

InterpolationsRegridder is GPU and MPI compatible in the simplest possible way: each MPI process has the entire input data and everything is copied to GPU.

Keyword arguments

The optional keyword argument extrapolation_bc controls what should be done when the interpolation point is not in the domain of definition. This has to be a tuple of N elements, where N is the number of spatial dimensions. For 3D spaces, the default is (Interpolations.Periodic(), Interpolations.Flat(), Interpolations.Throw()).

ClimaUtilities.Regridders.regridFunction
regrid(regridder::TempestRegridder, date::Dates.DateTime)

Return the field associated to the regridder at the given date.

regrid(regridder::InterpolationsRegridder, data, dimensions)::Field

Regrid the given data as defined on the given dimensions to the target_space in regridder.

This function is allocating.