`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:

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.
InterpolationsRegridder uses Interpolations.jl to perform non-conservative linear interpolation onto lat-long(-z) and x-y-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.

Currently, TempestRegridder does not support regridding on 3D domains. The InterpolationsRegridder described below can be used for these cases.

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.

Did you know?

With versions of ClimaUtilities after v0.1.24, you can choose the mode of the gridded interpolation with the keyword argument interpolation_method. For example, to do constant interpolation, you can pass interpolation_method = Interpolations.Constant() as a keyword argument when constructing the regridder.

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

By default, InterpolationsRegridder assumes you are interpolating on a globe and the default extrapolation boundary conditions are: periodic (along longitudes), copy (along latitude), and throwing an error (along z). These can be changed by passing the extrapolation_bc to the constructor of the regridder.

FAQ: How do I enable linear extrapolation in z?

Create the regridder like this:

import Interpolations as Intp

extrapolation_bc = (Intp.Periodic(), Intp.Flat(), Intp.Linear())
regridder = InterpolationsRegridder(target_space; extrapolation_bc)

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.TempestRegridder — Function

TempestRegridder(target_space::ClimaCore.Spaces.AbstractSpace,
                 varname::AbstractString,
                 input_file::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.

source

ClimaUtilities.Regridders.InterpolationsRegridder — Function

InterpolationsRegridder(target_space::ClimaCore.Spaces.AbstractSpace
                        [; extrapolation_bc::Tuple,
                           dim_increasing::Union{Nothing, Tuple},
                           dim_names::Union{Nothing, Tuple}
                           interpolation_method = Interpolations.Linear()])

An online regridder that uses Interpolations.jl

Currently, InterpolationsRegridder is implemented for LatLong, LatLongZ, XYZ, and Z 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. For Z spaces, it throws errors when extrapolating. 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()).

The optional keyword argument dim_increasing controls which dimensions should be reversed before performing interpolation. This must be a tuple of N booleans, where N is the number of spatial dimensions. The default is the true for each spatial dimension.

The optional keyword argument dim_names provides dimension names for the input data (e.g., ("lon", "lat", "z")). When provided with dim_increasing, they must be in the same order: dim_increasing[i] applies to dim_names[i] and the i-th dimension. This is particularly important for Z-only spaces where vertical dimensions need to be identified by name.

Centers of cells heuristic for longitude dimension

For the longitude dimension, the points along the dimension can either represent the centers of cells or the edges of cells. InterpolationsRegridder automatically detects whether the points represent the centers of cells or the edges of cells by checking if the dimension is equispaced and spans all 360 degrees. When this condition is met and a periodic boundary condition is used, then the points are treated as the centers of cells.

source

ClimaUtilities.Regridders.regrid — Function

regrid(regridder::TempestRegridder, date::Dates.DateTime)

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

source

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.

source